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PREFACE 



This publication is the reference manual for KSAM/3000. KSAM stands for Keyed Sequential 
Access Method, a method of accessing files indexed by keys. KSAM/3000 operates on the HP 3000 
Computer System. 

The methods used to access a KSAM/3000 file differ depending on the particular language used. A 
COBOL user, an RPG user, a BASIC user, and an SPL user each has his own set of procedures with 
which to access a KSAM file; a FORTRAN user can choose to access a KSAM file with either 
COBOL or SPL procedures. All users can create, copy, purge, or perform other utility functions 
with the KSAMUTIL and FCOPY programs. 

This manual is organized so that the more general functions available to all users are described in the 
first two sections followed by a section describing KSAM access from each of the four languages: 
COBOL, SPL, FORTRAN, and BASIC. Access to KSAM files from an RPG program is not 
described in this manual, but is included as part of the RPG manual: 

RPG/3000 Compiler Application & Reference Manual (32104-90001, Second Edition, 2/77) 

In order to use this manual effectively, you should be familiar with the MPE Operating System and 
with FCOPY. Also, it is assumed that you are familiar with the language in which you are program- 
ming. The following manuals contain all the information you might need as a supplement to this 
manual: 

MPE Commands Reference Manual (30000-90009) 

MPE Intrinsics Reference Manual (30000-90010) 

FCOPY/3000 Reference Manual (03000-90064) 

COBOL/3000 Reference Manual (32213-90001) 

SPL/3000 Reference Manual (30000-90024) 

EDIT/3000 Reference Manual (03000-90012) 

FORTRAN/3000 Reference Manual (30000-90040) 

BASIC/3000 Interpreter Reference Manual (30000-90026) 

BASIC/3000 Compiler Reference Manual (32103-90001) 

System Manager/System Supervisor Reference Manual (30000-90014) 

Using Files (30000-90102) 

SECOND EDITION 

The second edition of the KSAM manual provides the following new information: 

• Full syntax for and description of how to use the new KSAMUTIL commands: 
KEYSEQ, KEYDUMP, and KEYINFO. (section II) 

• Enhancements to the KSAMUTIL utility to allow abbreviated command names, 
offline listing of displays, and entry of MPE commands from KSAMUTIL. (section II) 

• Discussion of record pointer positioning in all languages; with special emphasis on 
using the record pointers for shared access, (sections III, IV, VI) 

• Description of how pointers are set internally, (appendix B) 

• Discussion of recovery procedures in case of system failure, (appendix E) 

In addition, there are minor corrections throughout the manual as well as documen- 
tation of minor enhancements. 

This edition covers the version of KSAM number A.02.04 release on the 1918 IT. 



CONVENTIONS USED IN THIS MANUAL 



NOTATION 

[] 



{} 



DESCRIPTION 

An element inside brackets is optional. Several elements stacked inside a pair of brackets means 
the user may select any one or none of these elements. 



Example: 



H 



user may select A or B or neither 



When several elements are stacked within braces the user must select one of these elements. 



Example: < B > user must select A or B or C. 



italics 



underlining 



Lowercase italics denote a parameter which must be replaced by a user-supplied variable. 

Example: CALL name 

name one to 15 alphanumeric characters. 

Dialogue: Where it is necessary to distinguish user input from computer output, the input is 
underlined. 



Example: NEW NAME? ALPHA 1 

A horizontal ellipsis indicates that a previous bracketed element may be repeated, or that elements 
have been omitted. 
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OVERVIEW 



The Keyed Sequential Access Method (KSAM) is a method of organizing records in a file according 
to the content of key fields within each record. As implemented for the HP 3000 computer 
system, KSAM/3000 is similar to and competitive with other indexed sequential access methods. 

Every record in a KSAM file contains a primary key field whose contents determine the primary 
logical sequence of records in the file. Other key fields can also be defined so that the file can be 
sequenced in alternate orders. The order in which records are physically written to the file, the 
chronological order, can be the same as the primary key sequence or it can be unrelated to any 
logical sequence. 

KSAM/3000 files can be accessed by programs written in any of these languages: 

RPG/3000 

COBOL/3000 

SPL/3000 

FORTRAN/3000 

BASIC/3000 

KSAM/3000 files can be copied, listed, and otherwise manipulated with the utility programs: 

FCOPY/3000 

KSAMUTIL 

FILE STRUCTURE 

A KSAM/3000 file is organized into two distinct MPE files, a data file and a key file. The key file 
contains only key entries, the data file only data. Each record in the data file contains at least one 
item that is designated as a key. The value of each key is duplicated in the key file where all keys 
are ordered in ascending sequence. This organization allows records in the data file to be stored in 
any order since the key file maintains the logical order of records according to key value. 

Although it is not necessary to understand KSAM file structure in order to use a KSAM file, you 
may want to refer to appendix B for a detailed discussion of the relation between data and key 
files and the structure of the key file. 

NOTE 

In the total of 253 MPE files allowed for each process, one KSAM 
file counts as three files; two files for the data and keys, one for inter- 
nal maintenance. If all files are KSAM files, a maximum of 84 are 
allowed for each process. 
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FILE ACCESS 

Although separate in fact, the two files that comprise a KSAM file are treated as one file by the 
procedures that reference the file. The data file is the only file directly referenced by a user; the 
key file is updated by the system to reflect any changes to the data file and is not directly accessed 
by the user. Thus, from the user's point of view, accessing a KSAM file is very similar to accessing 
any other MPE file. 

KSAM/3000 provides the following ways to store and retrieve data: 

You can write records in logical sequence determined by primary key value or you can write 
records without regard to key sequence. 

You can read records in logical sequence determined by either the primary or an alternate key 
value . 

You can read a record selected at random by the value of its primary or alternate keys. 

You can read records in the order they were written, that is, in chronological sequence, unless 
the program is written in COBOL or BASIC. 

You can read a record selected by the value of its chronological record number, unless the 
program is written in COBOL or BASIC. 

You can update all the contents of an existing record including the contents of the primary 
key field. 

You can position to a record in the file according to its key value, its chronological record 
number, or its record number in key sequence. 

NOTE 

KSAM files are sequenced in ascending order only, not in descending 
order. Character keys are ordered by the ASCII collating sequence 
where numbers precede letters, not in the EBCDIC sequence where 
letters precede numbers. Numeric keys are ordered in algebraic order. 
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KSAM/3000 FEATURES 



KSAM/3000 provides a number of features beyond the standard indexed sequential access method. 
These include: 

Multiple Keys 

Duplicate Key Values 

Retrieval by Generic Key 

Retrieval by Approximate Match 

Fixed or Variable Length Data Records 

MULTIPLE KEYS 

Each data record can contain from one to sixteen keys. Of these keys, one is required, called the 
primary key; any others are alternate keys. For example, in an employee record, the primary key 
could be the employee's social security number; alternate keys might be the employee's name, 
phone number, or zip code. The values in these key fields determine the orders in which data 
records are sequenced. 

PRIMARY KEY. One field in each data record is defined to contain the primary key. The value 
in this field determines the primary sequence of records in the data file. Records are sequenced 
according to this primary key unless sequencing by an alternate key or in chronological order is 
specifically requested. 

ALTERNATE KEYS. Other fields within each data record can be designated as alternate keys to 
be used for alternate sequencing of records. Up to 15 alternate keys can be designated for each 
record, however, each additional alternate key adds to the overhead and can affect performance 
when accessing and maintaining a file. The file can be sequenced in a different order for each 
alternate key defined for the file. 

Note that alternate keys bear no hierarchical relation to each other or to the primary key. Each 
key is ordered in sequence by its value and type with no relation to other keys. In KSAM, sequence 
always means ascending sequence according to the ASCII collating sequence, (refer to appendix C.) 

DUPLICATE KEYS 

Sometimes it is essential that key values be unique (for example, a social security number), and at 
other times duplicate key values should be allowed (for example, a zip code). To provide for both 
cases, KSAM allows you to declare that any key may have a duplicate value while disallowing 
duplicate key values as the default condition. Allowing or disallowing duplicate key values applies 
to both primary and alternate keys. Duplicates can be allowed for one or more keys while being 
disallowed for other keys. 

NOTE 

Duplicate keys can greatly increase the time required to load or access 
a record with a duplicated key value. This is particularly true when 
there are a large number of duplicated key values in a large file. As a 
result, duplicate keys should only be used when other methods are 
not practical. For example, you should not make a key of an item 
that can only have two values, such as "MALE" or "FEMALE." 
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GENERIC KEYS 

During retrieval by key value you can choose to use part of a key rather than the entire key. Called 
generic keys, such partial keys allow you to retrieve a set of records whose key values differ in their 
entirety but share a common value at the beginning. Generic keys must begin at the first character 
of the defined key field and be shorter, not longer, than the defined key length; also, the key type 
must be BYTE, INTEGER, or DOUBLE. Suppose a key field containing a zip code is defined as five 
characters long. By specifying only the first three characters for retrieval it is possible to read all rec- 
ords whose zip code begins with a particular group of numbers. 

NOTE 



Generic keys cannot be used when accessing KSAM files 
through RPG. 



Record 
No. 



key field 



90021 



95060 



90291 



90027 



95050 




records retrieved by 
generic key- 





95050 






95060 






95065 











In this example of generic key retrieval, records 
with first 3 characters of zip code key field = 950 
are retrieved. 



APPROXIMATE MATCH 

When retrieving by key value, you can specify that the key you are looking for have a value that 
exactly matches a specified value, or you can specify that it bear a certain relation to a specified 
value. The choices are: equal to, equal to or greater than, or greater than. The last two relations 
let you search for an approximate match. For example, you can retrieve all records with a date 
greater than or equal to a given date: 



Record 

No. 



key field 





01/26/76 






01/28/76 






01/30/76 






02/02/76 






02/02/76 






02/05/76 






02/06/76 











records retrieved by 
approximate match ' 




In this example of approximate match, all 
records with a key field date greater than or 
equal to 01/31/76 are retrieved. 
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DATA RECORD FORMAT 

Every key entry in the key file contains, in addition to the key value, a pointer to the corresponding 
data record in the data file. The data records can be either fixed length or variable length. If they 
are fixed, the data record pointer specifies a record number relative to the beginning of the file. If 
the records are variable length, then the pointer indicates the start of the data record as a word off- 
set from the beginning of the file. 



Data File 



Pointer from Primary Key to Data Record 



^> 



Pointer from Alternate Key to Record 





STEVENS 


JOHN 


Z044-24-0474 

S S ff/SSSSSfS. 


M 


HOLLYWOOD 


CA 




GORHAM 


MARY 


516-37-9272 


F 


SANTAROSA 


CA 




^A.BR.AMS^^ 


RALPH 


214-77-3142 


M 


BURBANK 


CA 




STEVENS 


SUSAN 


334-27-0303 


F 


HOLLYWOOD 


CA 

















Key File 




GORHAM 



STEVENS 



STEVENS 



r f\AA O/l C\A~1A'/ 



/// 044-24-0474^ 



214-77-3142 



334-27-0303 



516-37-9272 



Primary 
Keys 



V 



Alternate 
Keys 



Figure 1-1. A Simplified View of the KSAM File Structure 
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HOW TO USE KSAM FILES 



Although a KSAM file consists physically of two separate files, a data and a key file, it is treated as 
one file for most purposes. For example, reading from a KSAM file in primary key sequence is 
equivalent to reading sequentially from a non-KSAM file. Similarly, creating the data file portion of 
a KSAM file is equivalent to creating a non-KSAM file. 

CREATING A KSAM FILE 

A KSAM file can be created in two ways: interactively with the > BUILD command of the utility 
program KSAMUTIL, or programmatically with a call to the MPE file system intrinsic FOPEN. (A 
COBOL or BASIC programmer can create a KSAM file only through the > BUILD command, not 
FOPEN.) Whether > BUILD or FOPEN is used, file creation consists of creating a data file in very 
much the same way you would create any HP 3000 file. The name assigned to the data file is the 
name by which the KSAM file is known. Then, as part of the file creation procedure, a key file is 
created and each of its keys defined by type, location in the data record, and size. If duplicate key 
values are to be allowed, this is specified as part of the key definition. 

WRITING RECORDS TO A KSAM FILE 

You can write records to a KSAM file in either of two ways. In one, records are written in any 
order regardless of primary key values. In the other, records are written in order according to the 
value of the primary key in each record. In the first case, the chronological sequence in which 
records are written differs from the logical record sequence determined by primary key. In the 
second, the chronological and logical record sequence is the same. When you specify that records 
are to be written in primary key sequence, KSAM checks to make sure that this sequence is fol- 
lowed and issues an error message if not. 

You can specify that the file be cleared of any existing records before writing new records to the 
file, or you can write records following any previously written records. The choice is made when 
you open the file. 

In any case, when records are written to the data file, the key file structure is modified automatically 
in order to place all keys in the new record into their proper sequence. 

Records cannot be written directly to a KSAM file according to a relative record number. 

RETRIEVING RECORDS FROM A KSAM FILE 

Records can be retrieved in a variety of ways: 

• Sequentially in the order determined by key value; either the primary or an alternate key can 
be selected to determine the order. 

• At random according to the value of a specified key; either the primary or an alternate key can 
be selected for the matching process. 
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• Chronologically in the order the data records were written.* 

• At random by chronological record number.* 

*The starred access methods are not available to a COBOL or BASIC programmer. 

Whenever duplicate keys are used and retrieval is by key value, the first key encountered deter- 
mines the record read. When generic keys are used, the smallest key value is selected first. Again, 
if there are duplicates in generic key values, the first key encountered is selected. 

UPDATING RECORDS IN A KSAM FILE 

You can change the contents of an existing record by program calls that read the record into 
storage where you update it and then write it back to the file. The updated record overwrites 
the existing record in its current location if the new record and the old record are the same length. 
Otherwise, the new record is written to the end of the file and the old record is marked for 
deletion. 

POSITIONING IN A KSAM FILE 

Record pointers can be positioned: 

• To a record determined by key value using either the primary or an alternate key. 

• To a record determined by its record number relative to the first record in key sequence, 
where the key is either primary or an alternate. ** 

• To a record determined by its record number relative to the first record written to the file 
(chronological sequence).** 

**Not available in COBOL or BASIC program. 



DELETING RECORDS FROM A KSAM FILE 

Records are not deleted physically from the data file. In order to delete a record, you call a proce- 
dure that tags the record for deletion by writing a delete code in the first two characters of the 
record. Any subsequent access skips such records as if they were not there. In addition, the key 
file is reorganized automatically so that the keys in the deleted record are no longer in the path 
that defines key sequence. Space in the key file from deleted key entries is re-used. In order to 
maintain the file's chronological order, space from deleted data records is not re-used. 

Because the data record is not physically deleted, it is possible to reconstruct a deleted record by 
copying the data file using the NOKSAM option of FCOPY. This provides back-up in case a record 
is deleted by mistake. 

REORGANIZING A KSAM FILE 

If many records have been deleted, thereby using a great deal of physical space in the file, you can 
compact the file by using FCOPY/3000 to copy only the active records, those not tagged for dele- 
tion to a new KSAM file. You can also use FCOPY to delete, add, or change alternate keys by 
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copying the file to a new KSAM file with a different key definition. When the key definition is dif- 
ferent, you must first create the new file with the > BUILD command of KSAMUTIL. 

SHARED ACCESS TO KSAM FILES 

Several programs can access the same KSAM file simultaneously. Shared access is assumed when 
the file is only being read, exclusive access is assumed when the file is being written to or updated. 
Thus, you can choose to make all your access shared or all exclusive. Note that shared access uses 
more memory than exclusive access since each open KSAM file requires a separate extra data 
segment. 

When access to the file is shared, it is each user's responsibility to dynamically lock the file before 
changing it in any way. The file must be locked before any records in the file are written, updated, 
or deleted, and then unlocked immediately after such action. By requiring this action, the system ' 
makes sure that the most recent values are brought into each user's buffer at each access. Any call 
to read or position to a record for sake of subsequent access should be within the locked portion 
of code that includes the actual update call. 

(Refer to appendix E for a full discussion of shared access.) 



RECOVERY AND ANALYSIS OF KSAM FILES 

The utility program KSAMUTIL provides several commands that can be used to analyze KSAM 
files. These commands allow you to check any key sequence to obtain a formatted dump of the 
key file, and in the event of a system failure, to check key file structural damage, determine 
whether key values are missing, and recover key values and data records by resetting end-of-file 
pointers. The command, KEYINFO, that performs these recovery functions must be run in case 
of a system failure while a KSAM file is open. (A full discussion of these commands is found in 
section II; also refer to appendix E for a discussion of KSAM file recovery in the event of system 
failure.) 

USING FILE EQUATIONS WITH KSAM FILES 

KSAM opens the key and data file allowing file equations for both. KSAM accesses the files in a 
very specific way. Since file equations will override any aoptions that KSAM uses, it is possible to 
specify access parameters on the file equation which will cause unpredictable results. The following 
should not be used on a file equation which references a KSAM file: 

BUF=numbers of buffers 

NOMR 

WAIT 

Refer to "Dynamic Locking" and "Exclusive Access" in Table 4-7, and the section on using FCOPY 
to add data to an existing file for further information. 
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HOW TO USE THIS MANUAL 

There are some differences in the way in which KSAM files can be accessed depending on the 
language in which you are programming. You should read the paragraphs below appropriate to 
your programming language and then turn to the last paragraph of this section, For All Program- 
mers. 

RPG PROGRAMMER 

This manual does not describe the code required to access a KSAM file using RPG. For this infor- 
mation, you must refer to : 

RPG/3000 Compiler Applications & Reference Manual 

COBOL PROGRAMMER 

If you are programming in COBOL, you should read section II in order to learn how to: 

Create, purge, rename, clear the contents, display the status of, or save a KSAM file. These 
functions are provided by the KSAMUTIL program. 

Copy a KSAM file to another KSAM file in any key order. 

Display the contents of a KSAM file in any key order on the standard list device. These 
functions are provided by the FCOPY program. 

You should read section III in order to learn how to: 
Open and close the KSAM file. 

Open the file for shared access and dynamic locking. 

Write the records to the file in sequential key order or in random order. 

Read records from the file in sequential order by key value or at random by key value. 

Change the key in preparation for a sequential read. 

Rewrite or delete an existing record. 

Dynamically lock or unlock the file. 

Note the following limitations for COBOL: 

You cannot pro grammatically create a KSAM file. You must use the > BUILD command 
of the KSAMUTIL utility program in order to create the file. 

You cannot read a KSAM file in chronological sequence. You can, however, use FCOPY to 
copy the file to a non-KSAM file and then read it in chronological sequence. 

For ANSII standard COBOL, only alternate keys, not primary keys, can be duplicated. 

SPL PROGRAMMER 

If you are programming in SPL, you should read section II in order to learn how to: 

• Create, purge, rename, clear the contents, display the status of, or save a KSAM file. These 
functions are provided by KSAMUTIL. 

• Copy a KSAM file to another KSAM file in any key order. 
MAY 1981 1-9 



• Display the contents of a KSAM file in any key order on the standard list device. These func- 
tions are provided by FCOPY. 

You may skip sections III, V, and VI, which apply to programming in COBOL, FORTRAN, and 
BASIC respectively. You should read section IV to learn how to: 

Create, open, and close a KSAM file. 

Write records to the file in sequential primary key order or in random order. 

Read records from the file in primary or alternate key order or in chronological order. 

Read records at random by key value. 

Read records directly according to a record number relative to the first chronological record. 

Position record pointer forward or backward a specified number of records in any specified key 
sequence. 

Position to a record defined by key value. 

Position to a relative record number in key sequence or in chronological sequence. 

Update or delete an existing record. 

Request access and status information on the KSAM file. 

Verify that input/output is completed, and verify that critical output is complete. 

Dynamically lock or unlock the file. 

Write or read user labels. 

In general, SPL programmers can use all the file system intrinsics provided for HP 3000 standard 
files with the following exceptions: 

A KSAM file cannot be renamed with the FRENAME intrinsic. 

A KSAM file cannot be positioned to a relative record number with FREADSEEK. (Similar 
functions are performed by the KSAM intrinsics FFINDBYKEY and FFINDN). 

A record cannot be written to a KSAM file according to relative record number with 
FWRITEDIR. 

The relation between two files (interactive or duplicative) cannot be determined with 
FRELATE. 
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FORTRAN PROGRAMMER 

If you are programming in FORTRAN, you should read section II in order to learn how to: 

• Create, purge, rename, clear the contents, display the status of, or save a KSAM file using 
KSAMUTIL. 

• Copy a KSAM file to another KSAM file in any key order with FCOPY. 

• Display the contents of a KSAM file in any key order on the standard list device using 
FCOPY. 

As a FORTRAN programmer can call either the COBOL procedures described in section III (and 
summarized above) or the intrinsics described in section IV (also summarized above). You should, 
therefore, read both these sections. Depending on your program requirements, you can then 
choose to use either the COBOL procedures or the file system intrinsics. Since these methods 
differ significantly in how the file is created and accessed, you should not attempt to combine 
calls to COBOL procedures with calls to the file system intrinsics. In general, the intrinsics 
provide more capabilities than the COBOL procedures. 

You should also read section V, which illustrates, by means of annotated examples, how to access 
a KSAM file through FORTRAN calls to the file system intrinsics. The examples illustrate: 

• Programmatically creating a KSAM file. 

• Writing records to a new KSAM file. 

• Reading the records in sequential order by primary key value and then by alternate key 
value. 

• Reading the records in chronological order. 

BASIC PROGRAMMER 

As a BASIC programmer you should read section II in order to learn how to: 

• Create, purge, rename, clear the contents, display the status of, or save a KSAM file using 
KSAMUTIL. 

• Copy a KSAM file to another KSAM file in any key order with FCOPY. 

• Display the contents of a KSAM file in any key order on the standard list device using 
FCOPY. 

Since a BASIC programmer, like the COBOL programmer, cannot create a KSAM file program- 
matically, it is especially important to note how files are created with the BUILD command of 
program KSAMUTIL. Note also that BASIC programs cannot read a KSAM file in chronological 
sequence. You can, however, use FCOPY to copy the data file to a non-KSAM file and then read 
it in chronological sequence. 
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You can skip sections III, IV, and V, which apply to COBOL, SPL, and FORTRAN programming 
respectively, and read section VI, which describes the BASIC procedures to access KSAM files. 
These procedures enable you to : 

Open and close a KSAM file. 

Write records to a KSAM file in primary key or in random order. 

Read records from the file in sequential order by key value, or at random by key value. 

Change the key in preparation for a sequential read. 

Rewrite or delete an existing record. 

Dynamically lock and then unlock the file during shared access. 



ALL PROGRAMMERS 

Programmers using any of the languages that access KSAM files will probably need to refer to 
appendix A. This appendix contains an explanation of the error messages, condition codes, and 
status returns that can result from file access. 

Appendix B describes the internal structure of KSAM files. It illustrates how key entries are stored 
in a special B-Tree structure, and how KSAM file size is determined. It also explains how files are 
accessed through the extra data segments allocated to each open file. This appendix provides infor- 
mation for the sophisticated programmer who wants to know how KSAM files operate in order to 
improve performance. For the average user, the information in appendix B is not needed in order 
to create and use KSAM files. 

Appendix C provides the ASCII collating sequence used by KSAM/3000 to determine character key 
sequence; (numeric key sequence is in algebraic order). Note that the KSAM key sequence is in as- 
cending order only, the order in which the ASCII characters are shown in appendix C. 

Appendix D provides instructions that will help you convert your files to KSAM/3000 files. It tells 
you how to convert any serially accessible file to a KSAM file. If you are already using INDEX files, 
it describes use of the conversion program RTOKSAM for converting from INDEX to KSAM. Note 
that INDEX files were previously called RSAM files. 

Appendix E describes the recovery procedures to be used if the system fails when KSAM files are 
open. It explains what happens when a file is closed normally as opposed to what happens when a 
system failure prevents normal closing, and then tells the user exactly what to do when a system 
failure affects open KSAM files. 
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A pair of utility programs and a set of commands allow you to create and manipulate KSAM files. 



OVERVIEW 



The program KSAMUTIL provides MPE capabilities that allow you to manipulate KSAM files. With 
KSAMUTIL commands, you can create a KSAM file, rename both the data and key files, save a 
temporary file as a permanent file, clear all data from a file, purge a file, and verify the contents and 
access history of an existing file. 

The HP 3000 file copier, FCOPY, is adapted to copy KSAM files. FCOPY allows you to copy from 
a KSAM file to another file (KSAM or non-KSAM), in primary or alternate key sequence; to copy 
an entire file or a subset of a file, and to copy either the data or key file. 

The MPE commands : STORE and : RESTORE can be used with KSAM files to transfer the files 
from disc to magnetic tape and vice versa. 

The utility functions that can be performed on KSAM files are summarized in table 2-1. 

Both KSAMUTIL and FCOPY are programs resident in the system library that can be executed with 
the MPE :RUN command. When run in a session, each program responds by issuing a greater-than 
(>) prompt. You may then enter commands to control further operation of the program. Both pro- 
grams may be operated in batch mode as well as in a session. In batch mode, the greater-than prompt 
is not required. : STORE and : RESTORE are commands directed to the MPE command interpreter 
and can be included in either a job or a session. 
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Table 2-1. Summary of KSAM Utilities 



UTILITY 


OPTION/COMMAND 


FUNCTION 


KSAMUTIL 


>BUILDor>B 

>ERASE 

>PURGE 
>RENAMEor>R 

>SAVE or >S 

>VERIFYor>V 

>HELPor>H 
>EXITor>E 
>KEYSEQor>KS 

>KEYDUMPor>KD 
>KEYINFOor>KI 


Create KSAM file consisting of a data file and key 
file. 

Clear contents of KSAM data file and reset key 
file pointers. 

Remove KSAM file from system. 

Change name of KSAM key or data file to a new 
name. 

Save session/job temporary KSAM file as a 
permanent file. 

Display information on current status of data and 
keys in KSAM file. 

Request description of KSAMUTIL commands. 

Exit from KSAMUTIL program. 

Check the sequence of any key (primary or alter- 
nate) in key file. 

Display a formatted, structural key file dump. 

Display information on current status of key file; 
in case of system failure, attempt recovery. 


FCOPY 


; K E Y=keyloca tion 
;NOKSAM 


Copy KSAM file in key sequence by a key spec- 
ified by its beginning location in record. 

Copy contents of key or data file in consecutive 
(physical) order. 

If both these parameters are omitted, the data file 
is copied in sequence by primary key; the key file 
is established with all links maintained. Other 
FCOPY options apply to KSAM files with minor 
exceptions (refer to table 2-4). 


MPE 


:STOR E data file, key file 
: RESTORE data file, key file 


Store KSAM data and key files from disc to 
magnetic tape. 

Restore KSAM data and key files from magnetic 
tape to disc. 1 
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KSAMUTIL UTILITY 

KSAMUTIL provides a number of capabilities, among which is the essential capability to create 
KSAM files For a COBOL, BASIC, or RPG programmer, KSAM files can be created only through 
the BUILD command of the program KSAMUTIL. Although SPL and FORTRAN programmers can 
create KSAM files with the FOPEN intrinsic (described in section IV), the BUILD command may 
still provide these users with the simplest method for creating a KSAM file. 

RUNNING KSAMUTIL 

To pass control to KSAMUTIL, use the MPE command: 

:RUN KSAMUTIL.PUB.SYS 

In a session, KSAMUTIL prompts with the greater-than sign (>) in column 1 to which you respond 
with the command you want to execute. In a job, you enter the command in column 1 of the 
record following the RUN command. No prompt character precedes the KSAMUTIL commands in 
batch mode. 

Refer to table 2-1 for a list of the KSAMUTIL commands and their functions. 

COMMAND ABBREVIATIONS. All KSAMUTIL commands, except ERASE and PURGE, can be 
abbreviated. Most abbreviations allow the first letter of the command name. For example, >BUILD 
can be specified as >B, and >EXIT can be specified as >E. The three command names beginning 
with K (>KEYDUMP, >KEYSEQ, and >KEYINFO) are abbreviated to two letters to distinguish 
one from the other. As shown in table 2-1, these abbreviations are, respectively, >KD, >KS, and 
>KI. 

RUNNING MPE COMMANDS FROM KSAMUTIL. Once you are running KSAMUTIL and you 
want to use an MPE command, you need not exit from KSAMUTIL and return to MPE; simply type 
the colon prompt (:) following the KSAMUTIL prompt (>) and then enter the MPE command. For 
instance, if you want to list the files in your account and group from KSAMUTIL, enter the LISTF 
command as shown: 



> : LISTF 

OPTION TO LIST DISPLAYS ON LINE PRINTER. Four KSAMUTIL commands display file infor- 
mation; these are VERIFY, KEYDUMP, KEYSEQ, and KEYINFO. Each of these has an option that 
allows you to list the information on a line printer rather than display it on your terminal. If you in- 
clude the keyword OFFLINE as an option in any of these commands, the requested information is 
sent to the line printer. If you want the list sent to a particular line printer, you can use a :FILE 
command naming the KSAM list file "KSAMLIST" as the formal designator. For example, suppose 
you are running KSAMUTIL and want to list the current information on a KSAM file and you want 
this information listed on a particular line printer: 

> :FILE KSAMLIST; DEV=SLOWLP -« select particular line printer 

> VERIFY MYFILE; OFFLINE -* specify output to go to an offline device 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4= ALL)? 4.^^^ 
all information request all information 

The resulting output is sent to the line printer identified as SLOWLP. 
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OPTIONAL PARAMETERS. Wherever a command parameter is shown with brackets, [ ] , that 
parameter can be omitted. For certain commands, SAVE, VERIFY, KEYDUMP, KEYSEQ, and 
KEYINFO, the filereference parameter is optional if no other parameters are specified. When this 
parameter is omitted, it assumes a prior command has specified a filereference and it uses the last 
filereference to identify the selected file. For example, assume you use the VERIFY command 
twice in a row, once to list the requested output on the line printer, and then to display it at your 
terminal. To do this, you can use the following command sequence: 

: RUN KSAMUTIL 

> VERIFY MYFILE; OFFLINE 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4= ALL)? 4 

(output is sent to the line printer) 

>¥~+ previous file reference to MYFILE is assumed 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4= ALL)? 4 

(output appears at your terminal) 

Note that you cannot issue these commands in reverse order because the filereference parameter 
can be omitted only if there are no other parameters. Thus, it is not legal to use command 
>VERIFY MYFILE followed by >VERIFY; OFFLINE. 

EXITING FROM KSAMUTIL 

When you have finished using KSAMUTIL in a session, you can return to the MPE operating 
system with the command: 



-EXIT or VE 

In a batch job, the EXIT command is specified in column 1 of the record that terminates the 
program; the greater-than sign is not included. The keyword EXIT can be abbreviated as E. 
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HELP 



Requests help using KSAMUTIL 



.(HELP} 



This command returns a summary description of each of the KSAMUTIL commands when entered 
at a terminal. The keyword "HELP" can be abbreviated to "H". 

REQUESTING HELP 

The HELP command lists all the valid KSAMUTIL commands and then asks if you need informa- 
tion on a particular command. When you enter the name of a KSAMUTIL command, HELP dis- 
plays the command syntax. HELP is terminated by entering N in response to the prompt MORE 

(Y/N)?. 

The following example illustrates the HELP command. User input is underlined. 
VALID COMMANDS AHE: 



BUILDIB3. 

ERASE.... 

EXITCE1.. 

PURGE.... 

HENAMEtRl 

SAVEIS*].. 

VERIFYtV) 

KEYINFOCKI 

KEYDUMP[KD 

KEYSEQCKS] 



.TO CREATE A FILf 

.TO RESET A FILE T° INITIAL CONDITIONS 

.TO LEAVE THIS RnilTINt 

.TO DELETE A FILf 

. 10 RENAME A FILf 

.10 RtTUN A TEMPORARY FILE 

,|0 DLSCRIRF FILf CHARACTERISTICS 

.TO OBTAIN KEY File informations 

.TO ObTAlNj FORMATTED KEY FIlE STRUCTURAL 

.TO CHECK THE SEpUtNCf OF KFY FILE 



DUMP 



MORE <Y/N)?Y_ 

ENTER COMMAND NAME I B_ 

BUILD <DATAFILEREF> 
t JDEV=<DEVICE>3 

c;disc=[<numreoh»<n<jnextents>i[ , <INITAL|.0C>3 3 3 

[REC=t<RECSlZF>3C»[<BL0CKFACT0p>][ t IFW1 1 , BInARYX. ASCI 13 3 1 3 

t ITEMPI 

C ;C0DE=<FILEC0DE>] 

IKEY = <TYPE>, <POSITION>[ . f <LFNGTH>3 r » I <BL0cMNG> 3 t . DUPLICATE 3 3 3 

[♦RDUP3 
IlKEY = <TYPE>.<POSIT10N>r , f <LENrtH> 3 £ t [ <BLOCi\j.nG> 3 [ »DllPL 1CATE 3 3 3 ...3 

C.RDUP333 ...3 
[ »LABELS=<NUMBERLABELs>3 
t »FIRSTREC=0;i3 
[»KEYDEV=<UtVlCE>] 
»KEYFILE=FILEREFERENCE2 
[»KEYENTRIES=<NUMBER>] 

<TYPE>: :=B\D\I\R\L\N\P\» 
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MORE <Y/N)?Y 

ENTER COMMAND NAME: E 

EXIT 

MORE (Y/N)?Y_ 

ENTER COMMAND NAME: ERASE 

ERASE <FILEREFEHENCE> 

MORE (Y/N)?Y_ 

ENTER COMMAND NAME: PuRGF 

PURGE <FILEREFERENCE>[ .TFMP] 

MORE (Y/N)?Y_ 

ENTER COMMAND NAME: J± 

RENAME <OLDFILFRtF>t<NEWFTLEREF>l»TEMP] 

MORE (Y/M)?I 

ENTER COMMAND NAME : S^ 

SAVE [<TEMPFiLE«EF>] 

MORE (Y/N)?Y 

ENTER COMMAND NAME: V 

VERIFY [<FlLFREf r ERENCF>l 
H OFFLINE] 
tlNOCHECK] 
MORE (Y/N)?Y 

ENTER COMMAND NAME: Kn 

KEYDUMP f<FlLERtFERENrE>] 
CJSEO=<KEYSEquENCE>3 
t»SUBSET=[[D<P°SITION>J[,<NUMRER>] J 

I I 

P'CHAR-STRING"] 
[|FILE=<FILEREFtRENCEi>] 
I I 

UOFFLINE J 

IISOHTJ 
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MORE (Y/M)?I 

ENTER COMMAND NAME: Kl 

KEYINFO [<FILEREFERENCE>] 
[;OFFLINE] 
[ ; RECOVER] 

MORE (Y/N)?X 

ENTER COMMAND NAME: KS_ 

KEYSEO t<FILEREFERENCE>] 
t ISEQ=<KEYSEQENCE>] 
C »OFFLINF3 
[IN0LIST1 

MORE (Y/N)?N ■« termina te HELP display 

>E 

END OF PROGRAM 
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Creates a KSAM file. 



(B 

I BUILD \ filereference 1 

[;REC=[recsize] [,[blockfactor] [, 



".binary] 

^ASCII J 



I I 



.DP'V-rft'i-'ic"*;] 

DlSC=[numrec] [,[numextertts] [Jnitialloc] ) ] 



■.KEYFlLE-TiU'refercniw 2 

iKKY-kcvlype, hey location. key$fcp[.[kcy blocking] 

[;KEY=keytype, keylocation, key $ize[,[key blocking] 



[;KEYENTRIES=numentries] 
[;LABELS=numlabels] 
[■KEYBEV=device] 
[;FlRSTREC=recnum] 



".DUPLICATE " 

,DUP 

,RDUPLICATE 
_,RDUP 

".DUPLICATE " 
,DUP 

.RDUPLICATE 
.RDUP 



The BUILD command of the KSAMUTIL utility program is used to create a KSAM file and 
allocate the file to a mass storage device. Although this command is similar to the MPE :BUILD 
command, it has been modified for KSAM files. You can specify the BUILD command with 
the abbreviation, B. 

NOTE 
You cannot create a KSAM file with the MPE :BUILD command. 

If you are programming in COBOL, BASIC, or RPG, you must use the KSAMUTIL BUILD com- 
mand to create a KSAM file; in SPL or FORTRAN, you can create a KSAM file either with the 
BUILD command or with the FOPEN intrinsic (described in section IV). 



PARAMETERS 

filereference 1 



Actual file designator. This is the name that identifies the KSAM file 
(both data and key files) and also identifies the data file when specified 
independently of the key file. It has the form: 

filename [/lockword] [.groupname [.accountname] ] 
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REC=recsize 



blockfactor 



All four sub-parameters are names that contain from 1 to 8 alphanu- 
meric characters, beginning with a letter. 

NOTE 

If specified, account name must be that of your log-on 
account; you cannot create a file in another account. 

If fUe has no lockword and belongs to your log-on group, only filename 
is necessary. 

(Required parameter.) 

Size of logical records in file. If a positive number, this represents 
words; characters are represented by a negative number. If the records 
are variable length, recsize indicates the maximum length allowed for 
a logical record. 

Block size is determined by multiplying the specified recsize by 
blockfactor. For binary files or ASCII files with fixed-length records, 
an odd character count is rounded up to the next highest even number 
to insure that the record starts on a word boundary. The rounded 
number should be used in calculating block size since a block always 
starts on a word boundary. 

(Optional parameter.) 

Default: The configured record size, of the particular device is used 
when recsize is omitted; for disc files, the value used is 256 characters 
or 1 28 words. 

An integer equal to the number of logical data records in each block. 
This integer should result in a data block size smaller than 4096 (4K) 
words. The blockfactor is used to calculate the buffer size established 
for transfer of data to and from the file. 

For fixed-length records, blockfactor is the actual number of records 
in a block. For variable-length records, blockfactor is a multiplier 
used with recsize to calculate block size: 

block size = ( (recsize+1) * blockfactor) +1 

The calculation is performed in words, not characters. 

(Optional parameter.) 

Default: calculated by dividing the specified recsize into the configured 
block size; the result is rounded down to an integer never less than 1. 



Data file contains fixed -length records. 
(Optional parameter.) 
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v 



BINARY 



ASCII 



TEMP 



DEV =device 



Data file contains variable-length records. Since KSAM performs its 
own blocking and deblocking, a KSAM data file specified as variable- 
length is treated by MPE as a file with fixed-length records, each re- 
cord the size of a KSAM block (refer to blockfactor above for calcu- 
lation of block size). Although the MPE LISTF command shows the 
data file as fixed-length, the KSAMUTIL VERIFY command, option 
3, shows DATA FIXED as FALSE when the file is a variable-length 
KSAM file. 

(Optional parameter.) 

Default: If both F and V are omitted, records are fixed-length. 

Data file contains binary -coded records. 

(Optional parameter.) 

Data file contains ASCII-coded records. 

(Optional parameters.) 

Default: If both BINAR Y and ASCII are omitted, records are binary. 

File is created as a session/job temporary file; when the session or 
job terminates, the file is deleted from the session/job temporary 
file directory. 

(Optional parameter.) 

Default: If TEMP is omitted, file is declared permanent and is saved 
in the system file domain. 

device designates the device on which the data file resides. (The key 
file device is specified in the KEYDEV parameter.) device can be 
specified as a device class name of up to 8 alphanumeric characters 
beginning with a letter and terminated by any non-alphanumeric 
character such as a blank, or as a logical device number consisting of 
a three-character numeric string, or it can be a remote device identifier 
consisting of the device class name or logical device number followed 
by a pound sign (#) and a remote device class name or logical device 
number. 

Device class names and logical device numbers are assigned to devices 
during system configuration. (See System Manager/ System Supervisor 
reference manual). 

For KSAM files, the device must be a random access device such as the 
disc. If the file is a newly-created disc file specified as a device class 
name, then all extents to the file must be members of the same class. 
Similarly, if the device is identified by a logical device number then 
all extents must have the same logical device number. 

(Optional parameter.) 

Default: If omitted, the device class name DISC is used. 
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COBE=filecode 



DlSC=numrec 



Code indicates that the data file is specially formatted. The code is 
recorded in the file label and is available to processes through the 
FGETINFO intrinsic. It must be specified as a positive integer in the 
range through 1023. 

(Optional parameter.) 

Default: If CODE is omitted, the file code is 0. 

NOTE 

The CODE parameter applies only to data files; the key file 
code value is always 1080. 

Total maximum file capacity, in terms of logical records (for files con- 
taining fixed-length records) or blocks (for files containing variable- 
length records). Maximum file capacity allowed is 2,097,120 sectors. 



numextents 



initalloc 



KEY FILE=filereference2 



(Optional parameter.) 

Default: If omitted, 1 024 records is the default. 

Number of extents (continguously-located disc sectors) that can be 
dynamically allocated to the file as logical records are written to it. 
The size of each extent (in terms of records) is determined by the 
numrec parameter value divided by the numextents parameter value. 
Extents can allocated on any disc in the device class specified in the 
device parameter. If you want to ensure that all extents for a file re- 
side on the same disc, use the logical device number of that disc or a 
device class name relating to a single disc device, in the device param- 
eter. If specified, numextents must be integer value from 1 to 32. 

(Optional parameter.) 

Default: 8. 

Number of extents to be allocated to the file at the time it is opened. 
Must be an integer from 1 to 32. If attempt to allocate requested space 
fails, an error message appears. 

(Optional parameter.) 

Default: 1. 

Actual file designator. This is the name that identifies the KSAM key 
file. It has the format: filename, which is 1-8 alphanumeric characters 
beginning with a letter. Unlike filereferencel (the data filename) 
filereference2 may not be qualified by account or group names, nor 
may it contain a lockword. The key file contains all the key entries and 
key control information, whereas the data file contains the actual data. 
A KSAM file is always referenced by the data file name, filereferencel , 
not the key file name, filereference2. 

(Required parameter.) 
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KEY= 



One KEY specification must be included for each key in the KSAM file. 
The first occurrence of the KEY specification describes the primary 
key; each subsequent KEY specification describes an alternate key. 
There may be up to 15 alternate key descriptions in addition to the 
primary key description. 



key type 



keylocation 



keysize 



key blocking 



(Required parameter.) 

keytype is specified asCBYTE) INTEGER, DOUBLE, REAL, LONG, 
NUMERIC, PACKED, oV*PACKED. The whole word or only the 
first letter need be specified (for example, B is equivalent to BYTE). 
If more than the first letter is used, the word must be spelled correctly. 
(Refer to table 2-2 for a full description of each key type.) 
(Required parameter.) 

Location of the first character of the key within the data record count- 
ing from the first character in the record. The first character in the 
data record is always numbered 1- Only one key can start at the same 
location. 
(Required parameter.) 

Length of the key in characters. The length depends on keytype as 

follows: 

BYTE 1 to 255 characters 

INTEGER 1 to 255 characters (default = 2) 

DOUBLE 1 to 255 characters (default = 4) 

REAL 1 to 255 characters (default = 4) 

LONG 1 to 255 characters (default = 8) 

NUMERIC 1 to 28 characters 

PACKED 1 to 14 characters (odd number of digits) 

*PACKED 2 to 14 characters (even number of digits) 

(Required parameter for BYTE, NUMERIC, PACKED, and *PACKED 

key types; defaults are provided for INTEGER, DOUBLE, REAL, and 

LONG key types, as noted above.) 

Number of Iceys per block. The key blocking value is an even number 
greater than or equal to 4. It is used with the key entry size (keysize 
parameter) to determine the size of each key block according to the 
following formula: 

5 + ( ke y s jf e+1 . )+ 4)keyblocking = key block size in words 

/Li 

Five words are used for control information in each block, keysize 
specified in characters is divided by 2 to get the key size in words, and 
4 words are added for the pointers in each key entry. This key entry 
size in words is multiplied by the key blocking factor to determine key 
block size. If the key blocking value generates a key block size greater 
than 2048 (2K) words, the file cannot be created. 

The resulting key block size is rounded up to a multiple of 128 words. 
If the file has multiple keys, KSAM forces all key blocks to the same 
size and adjusts the number of keys per block accordingly. 

Note that the value you specify for keyblocking may be increased 
(never decreased) by the system in order to produce a blocking factor 
that does not waste disc space. Refer to appendix B for a discussion 
of how the system determines the most efficient blocking factor based 
on the value you enter for key blocking. 
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DUPLICATE 
DUP 



RDUPLICATE 
RDUP 



Key blocking can affect access time in that the smaller the key block, 
the more time it may take to retrieve a record using the key file. In 
many cases, the default blocking factor produces the most efficient 
key blocking. 

(Optional parameter.) 

Default: key blocking is set to a value that produces a key block size of 
1024 (IK) words. (Maximum size is 2K.) 

In order to allow duplicate key values, this word must be included in 
the KEY specification. If DUPLICATE (or DUP) is not specified, 
records with duplicate key values are rejected and an error message 
issued when such records are written to the file. DUP is a legal abbre- 
viation of DUPLICATE. When you use this option to specify dupli- 
cate keys, each new duplicate key is inserted at the end of the dupli- 
cate key chain. This maintains the chronological order of duplicate 
keys. 

This option specifies that duplicate keys are allowed and are to be in- 
serted randomly in the duplicate key chain. This method makes in- 
sertion of such keys faster, but does not maintain the chronological 
order of the duplicate key chain. 

(Optional parameter.) 

Default: If omitted, duplicate keys are prohibited. 



KEYENTRIES=numen£ries The value of numentries is used to determine the key file size. The 

value specified for numentries should be the maximum number of 
primary key entries expected. When there are alternate keys, KSAM 
automatically adjusts the key file size to accomodate each key in 
addition to the primary key. 

Normally, this parameter can be omitted since KSAM assigns it the 
value of numrec (number of fixed-length data records or blocks of 
variable-length records). If, however, the data records are variable 
length and there are many small records, the value of numrec may 
be too small. In this case, you should specify a value for numentries 
greater than the value of numrec. 

The number of key entries determines the size of the key file, the file 
limit. When a new KSAM file is created, the MPE end-of-file marker 
is set to this file limit rather than to the end-of-data as is normal for 
MPE files. This allows any key block to be accessed in case of system 
failure. To determine where the actual end-of-data is, use the KSAM- 
UTIL VERIFY command, option 3, and look at the heading KEY 
FILE EOF. This shows the record number of the next available key 
block (one record past the last used key block). 

(Optional parameter.) 

Default: the value of numrec in the DISC= parameter or its default 
value 1024 if it too is omitted. 
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LABELS=numlabels 



KEYDEV=deuiee 



FIRSTREC=recnum 



The number of user label records to be created for the KSAM data 
file. Up to 254 labels (1 less than the MPE maximum) can be specified; 
COBOL programmers are restricted to 8 labels. 

(Optional parameter.) 

Default: if omitted, numlabels is equal 0. 

The device on which the key file resides, specified as a device class 
name or a logical device number. A device class name indicates the 
general type of the device as a string of one to eight alphanumeric 
characters beginning with a letter and terminated by a non-alphanumeric 
character such as a blank. The logical device number is the three- 
character numeric string identifying a particular device. If the data 
file is created on a remote device, the key file is assigned to the same 
machine, and the key file device is specified in the KEYDEV= 
parameter. 

Device class names and logical device numbers are assigned to devices 
during system configuration. 

For KSAM files, the device must be a random-access device such as the 
disc. 

(Optional parameter.) 

Default: If omitted, the device class name DISC is used. 

Determines whether record numbers in the data file are to start with 
zero or one. If the integer 1 is specified, then records are numbered 
beginning with 1; otherwise they will start with 0. The only accept- 
able values for recnum are 1 and 0. 

Normally, record numbering in MPE files starts with zero, the default 
value for recnum. In order to be consistent with most commercial 
applications, you can specify FIRSTREC=1 to change the record 
numbering scheme so that data records are numbered starting with 1. 

(Optional parameter.) 

Default: if omitted, record numbering starts with zero. 



2-14 



BUILD 



KEY DESCRIPTION 

Each key is described by specifying key type, key position, key size, and, optionally, the blocking 
factor and whether duplicates are allowed. Key type and size are defined in Table 2-2. Note that 
default values are provided for keysize when key type is specified as INTEGER, DOUBLE, REAL, 
or LONG. Only BYTE, INTEGER, and DOUBLE type keys can be used as generic keys. 



Table 2-2. Key Types 



key type 



BYTE 



INTEGER 



DOUBLE 



REAL 



LONG 



NUMERIC 



PACKED 



keysize 
(In Characters) 



"PACKED 



1-255 



1-255 

(default = 2) 



1-255 
(default = 4) 



1-255 
(default = 4) 



1-255 
(default = 8) 



1-28 



1-14 
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Format 



Each character requires 8 bits of a computer word. A character may 
contain any of the HP ASCII character set consisting of letters of the 
alphabet, numbers, and special characters. (Refer to appendix C.) 

Single-word fixed-point format permits two's complement represen- 
tation of positive and negative integers. Bit is a sign bit and the 
remaining 15 bits define a quantity ranging from -32768 through 
+32767. 

Double-word fixed-point format is the same as the integer format 
except that two words are linked together to allow a 32-bit quantity 
with a range between approximately -2 billion and +2 billion. 

Floating-point format with bit zero as a sign bit, an exponent 
(biased by +256) in bits 1 through 9, and a positive fraction in the 
remaining 22 bits of the double word. This type cannot be used 
as a generic key. 

Long floating-point format uses four words; an exponent (biased by 
+256) in bits 1-9, as with the real number, and a positive fraction in 
the remaining 54 bits. This type cannot be used as a generic key. 

External decimal format in which each decimal digit requires one 
8-bit character and the sign is combined with the least significant 
digit. (Refer to Table 2-3 for the list of characters representing the 
digit/sign combinations.) This type cannot be used as a generic key. 

Packed decimal format in which each digit requires only 4 bits and 
the sign is specified as a hexadecimal number in the least significant 
4 bits (1100 or C is plus and 1101 or D is minus). This type cannot 
be used as a generic key. 

Same as PACKED except this key type contains an even number of 
digits. This type cannot be used as a generic key. 
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Table 2-3. Character Equivalent to Signed Digit for NUMERIC Keys 



POSITIVE VALUES 


NEGATIVE VALUES 


SIGNED DIGIT 


CHARACTER 


SIGNED DIGIT 


CHARACTER 


+0 


{ 


-0 


} 


+ 1 


A 


-1 


J 


+2 


B 


-2 


K 


+3 


C 


-3 


L 


+4 


D 


-4 


M 


+5 


E 


-5 


N 


+6 


F 


-6 





+7 


G 


-7 


P 


+8 


H 


-8 


Q 


+9 


I 


-9 


R 



CREATING A KSAM FILE 

Creating a KSAM file with the KSAMUTIL BUILD command is very similar to creating a standard 
HP 3000 file with the MPE command :BUILD except that a KSAM file includes a key file descrip- 
tion. As with standard files, the default values can be assumed for many of the file description 
parameters. 

To create a KSAM file from the KSAMUTIL program, you can start by simply naming the file as 
the first parameter of the BUILD command. The file name defines the data file portion of the 
KSAM file with the default options: fixed-length, 128-word, binary-coded records, blocked 1 
record per block. 

To fully define a KSAM file, you must also: 

• name the key file 

• define at least one key (the primary key) in terms of: 

type 

location in the data file 

size 

These parameters provide your minimum KSAM file description from which the file can be created. 
To illustrate: 

: PT.TN KSAMUTIL. PUB. SYS 

>BUI LP KSAMFI LE; KEYFI LE=KFILE; KEY= I ,21,2 
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This command assigns the name KSAMFILE to the KSAM data file; it names the key file KFILE, 
and defines the primary key as an integer that starts in character 21 of the record, and is two char- 
acters long. By default, the blocking factor of the keyfile provides key blocks 1024 words long, the 
maximum number of primary keys is set to 1023 (the same as the maximum number of data 
records), duplicate keys are prohibited, and record numbering starts with zero. 

File KSAMFILE is now created. Default values were used where possible so that the BUILD com- 
mand specification shown above is the minimum needed to create a KSAM file. You could create 
the same file, KSAMFILE, with the following BUILD command in which default parameters are 
specified. 



recsize 



I 



>BUILD KSAMFILE;F?EC=128.,.,F,3INAPY<£- 

> ;dev=disc& 

> ;C0DE=P!& 

> ; LAB ELS =3 & 

> tFinSTREC^S, m mextents 

> ;DISC=1023,8, 1A 

> ,*KEYFILE=KFILE& "'"""•^^^^i/iitfaHoc 

; KEY. I, 2 1,2*. nUmreC 

> ;keyentries=10234 

> ;keydev=disc 



-line continuation character 



key description 



\ 



numentries 



This specification of the BUILD command, although initially more cumbersome, documents the 
default values with which the file is created. Since the default keyblocking factor is a value cal- 
culated from the key size so that each key block is IK words long, it is not specified here. You 
can use the VERIFY command to find the value KSAM has assigned as a key blocking factor for 
any file you create using a default for this value. 

Only a primary key is defined for this file. Within the data file, this key is an integer that occupies 
characters 21 and 22 (word 11) of each data record. 



Character 1 



21 



7ZZZZZZZBZZZZZZZ 



Word 1 



11 -*- 



Primary Key 



> Data Record 



In the key file, the values in any key are ordered sequentially so that the next higher value can 
always be located. The key should not begin in the first two characters of the data record since 
these characters are set to all l's when the record is deleted. If the key value of deleted records 
need never be recovered, then this restriction can be ignored. 

For each alternate key in addition to the primary key, another KEY= clause must be included. 
Suppose a personnel file with a primary key containing an employee number, an alternate key 
containing a name, and another alternate key containing the person's age. The first two keys are 
specified as BYTE keys, the third is an INTEGER. The key file is blocked with 10 keys per block 
and the maximum number of primary keys expected is 3000: 
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: RUN KSAMUTIL.PUB.SYS 

> BTfILD EMPLOYEE; REP.g^^ ASCI I ;keyfile = empkey;keyentries = 3000j A 

> KEY=B.> 3> 1 1 j 1 0i & ~* primary key (employee number) 

* KEY=B.» 1 5.> 30/ 1 0; & - alternate key (employee name) 

'alternate key (employee age) 



KEY=I,51*2, 10- 



The keys are located in the data record as follows: 



1st alternate key 




23 

2nd alternate key 



Note that the keys need not be contiguous. In this example, the primary key is located nearer to 
the beginning of the record than the other keys. This is not a requirement; the primary key can 
physically follow any alternate keys in the record, although the primary key is always the first 
key specified in the BUILD command. For example, in the file FSAMPLE, the primary key starts 
in character 21 following a secondary key in character 3: 



: run ksamutil.pub.sys 

>build fsample;keyfile=fkeyj* 



> 

> 



KEY«N,gl* 12 i A -«- 
KEY=I,3>2 — , 



-primary key- 



alternate key 



*- '7///////////////////////77T/ 




> data record 
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Clears the contents of a KSAM file. 



> ERASE f dereference 



The contents of a KSAM file, both the data and key files, can be cleared to an empty state with the 
KSAMUTIL ERASE command. 

PARAMETERS 

filereference Actual file designator that identifies the KSAM data file. It is specified 

exactly like filereference 1 in the >BUILD command. 

(Required parameter.) 

CLEARING A KSAMFILE 

When ERASE is specified for a KSAM file, the end-of-file pointer that follows all data is reset to 
point to the first record in the data file. This position of the pointer is identical to its position 
when the file is created and before any data is written to the file. 

All pointers and control words in the key file are reset to indicate that the data file is empty. 
Note that the file is still created and new data may be written to it. 
For example, to clear the contents from the file identified as KSAMFILE: 
>ERASE KSAMFILE 
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Purges a KSAM file from the system. 

> PURGE f dereference [ ,TEMP] 

The KSAMUTIL PURGE command can be used to remove a KSAM file, both data and key files, 
from the system. Although the MPE : PURGE command can also be used, it must be specified 
twice, once for the data file and once for the key file. If you are programming in COBOL, BASIC, 
or RPG, you should use the KSAMUTIL PURGE command to purge a KSAM file. In SPL or 
FORTRAN you could also use the FCLOSE intrinsic (described in section IV) to purge a KSAM 
file. 

PARAMETERS 

dereference Actual file designator identifying the KSAM data file. Specified 

exactly like filereferencel in the >BUILD command. 

(Required parameter.) 

TEMP Must be specified if file is a temporary file in session/job temporary 

file domain. If omitted, a permanent file is assumed. 

(Optional parameter.) 

PURGING A KSAM FILE 

When PURGE is executed, the specified KSAM data file and its associated key file are removed 
from the system and can no longer be referenced. 

For example, to purge a temporary KSAM file called KTEMP: 

> PURGE KTEMP, TEMP 

KTEMP. KSAM. DA TAMGT A KKEY PURGED. 

To purge the permanent file KSAMFILE: 

> PURGE KSAMFILE 

KSAMFILE. KSAM. DA TAMGT * KFILE PURGED. 

The system prints the data and key file names of a successfully purged KSAM file. It also prints 
the group and account names in which the file was created (in this case KSAM and DATAMGT). 
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Renames either the data or key file of a KSAM file. 



IS 



R.RNAMKI ,...,. 

j oldfilereference, newfilereference [,TEMP] 



The KSAMUTIL RENAME command can be used to change either the KSAM data file name or the 
KSAM key file name to a new name. Following execution of RENAME, the data and key files 
retain their relation to each other. Note that if the MPE .-RENAME command is used, this relation 
is severed. The FRENAME intrinsic cannot be used to rename a KSAM file. 

PARAMETERS 

oldfilereference Current actual file designator identifying the KSAM data file or the 

KSAM key file, specified exactly like filereferencel or filereference2 
in the BUILD command. 

(Required parameter.) 

newfilereference New actual file designator in same format as oldfilereference. The file 

named by oldfilereference will be given the name specified by 
newfilereference. 

(Required parameter.) 

TEMP Indicates that old file was, and new file will be, a temporary file in the 

session/job temporary file domain. 

(Optional parameter.) 

Default: If omitted, permanent file is assumed. 

RENAMING A KSAM FILE 

You may rename either the data file or the key file, not both, with one >RENAME command. To 
rename the entire file, you must specify the RENAME command twice. Thus, to rename the data 
file KSAMFILE and its associated key file KFILE: 

> RENAME KSAMFILE, NEWDATA 
> RENAME KFILEjNEWKEY 

The relation between keys and data in the newly named files is the same as that in the files 
KSAMFILE and KFILE. 

If the data file being renamed was protected by a lockword, then this lockword must be specified 
on both the old and new files if it is to be retained. If the lockword is omitted, it is removed when 
the file is renamed. Note that a lockword is never specified when renaming the key file; the keyfile 
is protected automatically by any lockword assigned to its associated data file. For example, to 
assign a new lockword to the data file DATAFIL: 

>RENAME DATAFIL/LOCKA, DATAFIL/LOCKB-* new lockword 
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Note that the new file name need not be in the same group as the old file name. RENAME provides a 
way to move a file from one group to another. For example, to move the KSAM file DATAFILE 
with its associated key file KEYFILE from GROUPA to GROUPB: 

> RENAME DATAFILE.GROUPA,DATAFILE.GROUPB 

Note that only one RENAME command is used. This one command insures that both the data file 
and the key file are in the same group. 
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SAVE 

Saves a temporary KSAM file as a permanent file. 

^1| AVK ( [filereference \ 

A temporary KSAM data file and its associated key file are made permanent with the KSAMUTIL 
SAVE command. The keyword "SAVE" can be abbreviated to "S". 

PARAMETERS 

filereference Actual file designator identifying the session/job temporary file to be 

saved, specified exactly like filereference 1 in the > BUILD command. 

(Optional parameter.) 

Default: If omitted, last filereference is assumed. 

SAVING A KSAM FILE 

Assume that KSAM data file KDATA and its associated key file was created as a session/job 
temporary file; to save this file as a permanent file: 

> SAVE KDATA 
Both the data and key files are saved. 
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Displays access and status information about KSAM file. 



X 



VERIFY 



[filereference] [; OFFLINE] [; NOCHECKJ 



With the VERIFY command, you can request a display of the characteristics of a KSAM data file, 
both the static information defined at file creation and dynamic file access information. The ab- 
breviation V can be used instead of the keyword VERIFY. 



PARAMETERS 



filereference 



OFFLINE 



NOCHECK 



Actual file designator identifying the file whose characteristics are to 
be displayed. The actual designator can be a back reference to a file 
name in an MPE :FILE command; in this case, the actual designator 
must be preceded by an asterisk (*). Either the data file name or the 
key file name may be used to identify the KSAM file. 

(Optional parameter only if no parameters.) 

Default: If omitted, last filereference is assumed. 

Display output on line printer. An MPE :FILE command may be used 
to specify a particular line printer. 

(Optional parameter. ) 

Default: If omitted, display is sent to terminal. 

Allows specified KSAM file to be opened for read-only access by the 
VERIFY command; use when a system failure prevents the KSAM 
file from being opened. 

(Optional parameter.) 

Default: If omitted, VERIFY cannot open file that was open when 
system failed. 



DISPLAY KSAM FILE CHARACTERISTICS 

In a session, you will be asked to select one of four possible displays: 

1. File information (definitions from file creation plus file access statistics) 

2. KSAM parameters (definitions of keys from file creation) 

3. KSAM control (key file access statistics) 

4. All three of the above displays 

In a job, the entire set of displays is printed exactly as if option 4 had been selected in a session. 
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To illustrate the interaction, the following VERIFY commands select each of the three separate 
displays; if option 4 were selected, these displays would be printed consecutively with no halt 
until they were finished. User entries are underlined: 



>RUN KSAMUTIL.PUB.SYS 



select file information only 

\ 



HP32208A.2.4 TUE, APR 17, 1979, 11:23 AM KSAMUTIL VERSION: A. 2 .4 
> VERIFY TESTFILE 

WHICH (IsFILE INFO, 2=KSAM PARAMETERS, 3sKSAM CONTROL, 4=ALL)?i 

TESTFILE. JOAN. MORRIS CPEATOR=JOAN 

FOPTIONS(004005)=KSAM, ;FILE, NOCCTL, F, FILENAME, ASCII, PERM 
AOPTIONS(000400)=DEFAULT, NOBUF, DEFAULT, NO FLOCK, NO MR, IN 
RECSIZE!SUB!TYP:LDNUM:DRT:UN.j CODE:LOGICAL PTR: END OF FILE:FILE LIMIT 
-128: 9: 0: 2: 4: 1: 0: 0: 5: 1023 

LOG. COUNT:PHYS. COUNT;BLK SZ:EXT SZ:NR EXT: LABELStLDN: DISCADDR: 

l: l: -128: 129: 8: 0: 2:00000117760: 



The information returned by selecting file information is the same as that returned by FGETINFO 
(described in section IV). 

select key file information only 

I 
WHICH (1=FILE INFO, 2«KSAM PARAMETERS, 3=KSAM CONTROL, 4 = ALL)?2. 

KEY FILEsTESTKEY KEY FILE DEVICE=3 SIZE= 386 KEYS= 2 

FLAGWORD(000000)=RANDOM PRIMARY, FIRST REC0RD=0, PERMANENT 

KEY TY LENGTH LOC . D KEY BF LEVEL . .,.,.,-., 

* a 20 3Y 72 1 -* primary key is listed first, 

2b 8 24R 126 1 ■+ — alternate keys follow 

v s ■ random insertion of duplicate key 

corresponds to KEY= descriptions in BUILD command 

The actual number of keys per block (the blocking factor) is listed in this display under the heading 
KEY BF. Note that this number may be greater than the blocking factor you specified during file 
creation. This occurs if KSAM adjusts the specified blocking factor to generate a block size that 
makes optimum use of disc space. KSAM only increases the specified blocking factor, it never de- 
creases it. (Refer to appendix B for full particulars on the calculation of block size and the adjust- 
ment of the blocking factor.) 

The maximum number of levels in the key file structure for each key is noted under the heading 
LEVEL. 



2-25 



VERIFY 



select dynamic KSAM file information 



WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3 



DATA FILE = 


TESTFILE 




VERSIONS A. 2 


.4 










KEY CREATED* 


107/' 


'79 


10:58:17.4 


KEY 


ACCESS* 


107/'79 11:23:35.9 




KEY CHANGED* 


107/' 


'79 


11:: 


21: 7.7 


COUNT 


START: 


=107/'79 11:21: 8.0 




DATA RECS = 






5 


DATA BLOCKS* 






4 


END BLK WDS= 


64 


DATA BLK SZ= 






64 


DATA REC SZ= 






128 


ACCESSORS= 





FOPEN 






1 


FREAD 









FCLOSE 


1 


FREADDIR 









FREADC 









FREADBYKEY 





FPEMOVE 









FSPACE 









FFINDBYKEY 





FGETINFO 






3 


FGETKEYINFO 






1 


FREADLABEL 





FWRITELABEL 









FCHECK 









FFINDN 





FWRITE 






5 


FUPDATE 









FPOINT 





FLOCK 









FUNLOCK 









FCONTROL 





FSETMODE 





















KEYBLK READ 






3 


KEYBLK WROTE 






2 


KEYBLK SPLIT 





KEY FILE EOF 






18 


FREE KEY HD 









SYSTEM FAILURE 





MIN PRIME 






3 


MAX PRIME 






1 


RESET DATE 




DATA FIXED 




TRUE 


DATA B/F 






1 


TOTAL KEYS 


2 


FIRST RECNUM 









MIN RECSIZE 






31 







The dynamic key file information displayed by option 3 together with the static key file informa- 
tion displayed by option 2 comprise the information displayed by the FGETINFO intrinsic de- 
scribed in section IV. Note that the version number displayed by VERIFY is the version of KSAM 
under which the file was created. The intrinsic HP32208 described in section IV can be used to 
determine the current version of KSAM. 

TERMINATING THE > VERIFY COMMAND 

In order to terminate the VERIFY command in a session, you must press the RETURN key (CR) 
in response prompt: 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)? 

Any other response either causes a display followed by reiteration of this prompt or else causes this 
prompt to be issued. For example: 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS* 3=KSAM CONTROL, 4=ALL) ?6 

WHICH <1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL) 7%_ 

WHICH C1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL> ?CR 
> EXIT 

END OF PROGRAM only response to terminate VERIFY? 

DIRECTING VERIFY OUTPUT TO LINE PRINTER 

If you want a "hard copy" of the information displayed by VERIFY, you should use the OFFLINE 
option. When included, OFFLINE directs the VERIFY information to a line printer. You can use 
the : FILE command to specify a different output device or a particular line printer. 



2-26 



VERIFY 



USING VERIFY FOR RECOVERY 

In case of a system failure when a KSAM file is open, the VERIFY command provides the following 
useful information: 

• EOF marker on the data file (END OF FILE header in option 1) 

• EOF marker on key file (KEY FILE EOF header in option 3) 

• Flag indicating whether system failure occurred (SYSTEM FAILURE heading in option 3) 

• Number of processes that had opened the file for non read-only access when the system 
failure occurred (ACCESSORS heading in option 3). 

Note that you must use the NOCHECK option in order to run VERIFY when a system failure pre- 
vents KSAM files from being opened. This option overrides the restriction on opening files after a 
system failure and allows a file to be opened for read-only access in order to get the VERIFY infor- 
mation. (This access is not counted in the ACCESSORS count.) 

(Refer to the KEYINFO command description for an example of how the VERIFY information 
can be used for recovery after system failure.) 
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Verifies sequence of key values in KSAM file. 

KS ' | WwfcTi'wl UShQ^keyseqmmcMl j; OFFLINE j |:NOLJSIj 



This command compares all the key values in a particular key (primary or alternate) to determine 
whether they are in ascending sequence. If any values are out of sequence, a list of numbers ident- 
ifying such values is displayed, unless NOLIST is specified. In any case, the number of out-of-se- 
quence values is returned. Note that if key values are out of sequence, the key file is damaged and 
the KSAM file must be reloaded. 

The abbreviation KS may be used instead of the keyword KEYSEQ. 

PARAMETERS 



filereference 



SEQ=feey sequence 



OFFLINE 



NOLIST 



Actual file designator identifying the KSAM file whose key values are 
to be verified. Either the data file name or the key file name can be 
used to identify a KSAM file. Also, a back reference to a file named 
in an MPE :FILE command may be used. 

(Optional parameter if no parameters are specified.) 

Default: If omitted, the last file referenced is assumed. 

Identifies particular key whose key values are to be checked. Keys are 
numbered from 1. The first key (SEQ=1) is always the primary key; 
subsequent keys are alternate keys numbered in the order they appear 
in the record, such that the first alternate key in the record is SEQ=2, 
the second alternate key is SEQ=3, and so forth. 

(Optional parameter.) 

Default: If omitted, the primary key is assumed. 

Directs list of out-of-sequence keys to the line printer. An MPE : FILE 
command may be used to indicate a different output device than the 
line printer, or a particular line printer. 

(Optional parameter.) 

Default: If omitted, the list of out-of-sequence keys is displayed at 
user's terminal. 

Suppresses display of the particular key numbers whose values are out 
of sequence. A count of the out-of-sequence values is displayed even 
if NOLIST is specified. 

(Optional parameter.) 

Default: If omitted, list of key numbers for out-of-sequence key values 
is displayed. 
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VERIFY KEY SEQUENCE 

If you suspect that your key file has out of order key values in any key, you can run KEYSEQ. If 
any key values are not in ascending sequence, the key numbers associated with those key values are 
displayed. Note that the number of a key value refers to its position in the key file. For example, if 
the third, fourth, and fifth key values of a particular key are out of sequence, the numbers 3, 4, and 
5 are displayed. 

If the list of out-of-sequence key numbers is long, you can terminate it by holding down the CNTL 
key while typing Y (CNTL/Y). The total number of out-of-sequence key values will be displayed 
even if you terminate the list with CNTL/Y or suppress it altogether with NOLIST. 

Consider the following partial list of key values in the primary key of the KSAM file MYFILE: 



Key Value No. 
1 

2 

(D 
© 

5 
6 



Key Value 



ADAMS 



ADDISON 



ALAN 



ADLER 



ADRIAN 



AGEE 



■ key values out of order 



If you run KSAMUTIL and use the KEYSEQ command, as shown below, you can determine which 
keys are out of order: 



: RUN KSAMUTIL.PUB.SYS 
> KEYSEQ MYFILE ;SEQ=1 - 



■ test primary key sequence 



KEYSEQ displays the following: 

KEY VALUE # (FOR KEY VALUE OUT OF SEQUENCE) 
, _* & frf y numbers of keys with out-of-sequence values 

TOTAL # OF KEY VALUES READ 30 

# OF KEY VALUES OUT OF KEY SEQUENCE ORDER 2 

KEY FILE STRUCTURE DAMAGED, KSAM FILE HAS TO BE RELOADED 

Regardless of the number of key values that are out of sequence, you should reload the KSAM file 
to restore its integrity. 
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Consider a second example. Suppose MYFILE has two alternate keys, one starting in location 11 
(11th character of record) and another starting in location 33. To verify the sequence of key values 
in the second alternate key, execute KEYSEQ as follows: 



> KS MYFILE ;SEQ=3 ;NOLIST ^ suppress list of key numbers 

\— Z^—HZ — second alternate key 

TOTAL # OF KEY VALUES READ 30 

# OF KEY VALUES OUT OF KEY SEQUENCE ORDER 0- key values in sequence 



In this case all the key values were in correct sequence. Unless other keys in this file have values 
that are out of sequence, you need not reload the file. 

Note that NOLIST was specified. In general this is good practice. If any key values are not in 
sequence, the file should be reloaded, so it is seldom important to know which keys are out of 
sequence. 
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Provides formatted, structural dump of key file. 



.KEYDUMP) .... , , . avn , ' 

- * u ■'■ ':': | [fiiovjcrt'iicc] [;>,\:Q~ he, \. ■sequence j 






;SUBSKT- 



[;FILE=/bwia/des#nator] [;OFFLlNE] [;SORT] 



KEYDUMP 



[-"lposr'rjonl 



The key file dump consists of three items of information for each key value: 



1. Key Value 

2. Record Pointer 



3. Key Block Address 



The actual value of each key in ascending order 

The record number (fixed-length files) or word offset (variable- 
length files) of the data record to which the associated key value 
points. 

Relative record number of the first record in the key block con- 
taining the associated key value, followed within parentheses by 
the number of key values in the block. The addresses of key 
blocks at different levels are indented. 



This dump is very useful for examing the contents of any key file. Since key blocks are physically 
scattered throughout the key file, linked by pointers, it is difficult to follow an unstructured dump 
of a key file. The KEYDUMP display shows the contents of the key file, not as they are actually 
stored, but in a way that makes it much simpler to read than a dump of the actual file. 

One key at a time is dumped by KEYDUMP. If there is more than a primary key, you must run 
KEYDUMP for each key in order to dump the entire key file. 

Note that you can use CNTL/Y (the CNTL key held down while pressing the Y key) to stop display 
of this dump at any time. This is particularly useful if you display the dump at the terminal. Usually, 
however, you will use the OFFLINE option to list the dump on a line printer (see Parameter 
description, below). 

You can choose to dump a subset of the key file contents based on the key number or a key value. 
You can send the dump to a particular file and, if so, you can sort the key file contents by the re- 
cord number in the data file rather than by key value. You can also send the dump to a line printer. 



PARAMETERS 



filereference 



Actual file designator identifying the KSAM file whose key file is to be 
dumped; either the data file name or the key file name can be specified. 
The filereference can be a back reference to a file named in an MPE 
:FILE command. 



(Optional parameter if no parameters are specified.) 
Default: If omitted, the last file referenced is assumed. 
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SEQ=keysequence 



SUBSET= 



[-] position 



"string" 
,number 



FILE=filename 



Specify a particular key whose contents are to be dumped. The 
primary key, whatever its location in the data record, is always key 
number 1 (SEQ=1). Alternate keys are numbered according to the 
order in which they are specified in the BUILD command (or in 
ksamparam at FOPEN). The first alternate key is specified as 
SEQ=2, the next alternate key as SEQ=3, and so forth. 

(Optional parameter.) 

Default: If omitted, the primary key is selected. 

Select a portion of the key file to dump, based on the numeric position 
of the key or the key value, and the number of key values. 

Start dump with key whose number is specified. This number is the 
same as the key number issued by KEYSEQ. It corresponds to the 
position of the key value in the file in ascending sequence. Thus the 
first key value is position 1, the second is position 2, and so forth. 

The optional minus sign suppresses the normal indentation by key 
levels of the key block address display. 

Start dump with first key value greater than or equal to the specified 
string. 

Indicates the number of key values to be dumped starting with the key 
at the indicated position or whose value is indicated by "string". 

(Optional parameter.) 

Default: If omitted, all the key values for selected keys are dumped. 

Direct key file dump to specified disc file. A disc file (filename) will 
be created with a record size equal to the size of a key entry, that is 
key length (rounded up to full words) + four words. 

The four words are needed for the record pointer (2 words) plus the 
key block address (2 words). Note that a new file is always created, so 
do not name an exising file. 

The file has a default block size of IK words. Any of the file charac- 
teristics except the record size can be changed by a :FILE statement. 
For example: 

>:FILE FILEDUMP ;REC=,100 ;DEV=TAPE 
>KEYDUMP MYFILE ;FILE=*FILEDUMP 

These commands dump the primary key sequence to a tape with 100 
records per block. 

(Optional parameter.) 

Default: If omitted, key dump is sent to terminal. 
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OFFLINE 



SORT 



Direct output to a line printer. An MPE : FILE command can be used 
to indicate a different output device or a particular line printer. 

(Optional parameter.) 

Default: If omitted, the dump is sent to the user's terminal. 

Sort dump by record pointers rather than key values. The record 
pointers indicate the record number of the records in a data file with 
fixed length records or the word offset of the records in a data file 
with variable-length records. 

Note that this option can be used only when the dump is directed to a 
specific file with the FILE= option. 

(Optional parameter.) 

Default: If omitted, key dump is in ascending sequence by key value. 



DUMPING THE KEY FILE 

The dump produced by KEYDUMP consists of three columns: the first contains the key value, the 
second a pointer to a record number in the data file, and the third contains the key block address 
and the number of key values in that block. The key block address is given as the record number of 
the first record in any block. 

For example, assume that TESTFILE contains an INTEGER type primary key whose values we 
want to see. Run KEYDUMP as follows: 

: RUN KSAMUTIL.PUB.SYS 
>KEYDUMP TESTFILE 



The resulting dump consists essentially of three columns: one contains the key values in ascending 
sequence, another contains the record number (or word offset if record size is variable) of the as- 
sociated record in the data file, and the third gives the record address of the key block. A sample 

dump is shown below: 

record # (counting from ) 

of the data record in which 

i / K T7.Y RT.nrK ADR the key value is located 



key values in 

X ascending sequence 
KEY 



0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
0010 
0011 
0012 
0013 
0014 



REC. P TR.^ 

3 

5 

6 

2 

1 



4 

9 

7 

8 

10 

11 

12 

13 




relative record # of 1st 
record in key block 
(numbered from zero). 

Number of key values 
in this block. 

the block located at record 
#6 contains 2 key values; it 
is in a separate column because 
it is at a higher level of the key 
block structure. 
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This dump lists under the heading "KEY" 14 integer key values in ascending order from 0001 
through 0014. The next column under "REC.PTR." lists the record number of the data record 
associated with the key value — thus, key value 0001 is in record number 3 of the data file (the 
fourth record in chronological sequence), and key value 0006 is in the first record in the data file, 
record number 0. The third column under "KEY BLOCK ADR." shows the address of the key 
block in which each key value resides. The key block address is shown as the record number of 
the first record in the key block. (Note that KSAM key files use fixed length records each one 
sector long — 128 words. Thus, the record number is also the sector number. A key block consists 
of more than one sectors — default is 8 sectors). 

Key values are organized into blocks using a B-Tree structure (refer to appendix B for details). This 
structure has one or more levels where the first or highest level, is known as the "root" and lower 
levels are "leaves". This dump shows the level structure of the key file by indenting the key block 
addresses to correspond to levels. The highest or root level address is in the rightmost column, lower 
levels are listed to the left. By looking at the key block address, we see that the key block starting 
at record (sector) 6 is the root block, and that there are three key blocks at a lower level whose ad- 
dresses start, respectively, at records 2, 18, and 24. This key file has two levels; a key file with more 
levels would have correspondingly more columns under the key block address heading. 

The first time a key block address is listed, it is followed in parentheses by the number of key val- 
ues in that block. Looking at the dump, we see that the block starting at record 2 has 4 key values, 
the block at record 6 has 2 values, the block at record 18 has 5 values, and the block at record 24 
has 3. 

With this dump, we can picture the structure of the key file associated with the file TESTDUMP: 



record 2 



0001 



record 18 



■j: 



"Leaf" Blocks 



"Root" Block 



record 6 



0002 



0003 



0004 



r 



0005 



0011 



0006 0007 0008 0009 0010 



record 24 













. J 




0012 


0013 


0014 







The key values are shown within their key blocks; the dashed lines show the pointers that link key 
blocks in ascending sequence. 
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DUMPING A SUBSET OF THE KEY FILE 

If you want to dump a selected number of key values rather than all the values in a key, you can 
use the SUBSET option of KEYDUMP. The starting key value can be located in two ways: if you 
know the key number of the first key value you want displayed, use the SUBSET=position format; 
if you know the actual key value (or a value less than the key value), then you can use the SUB- 
SET; 11 "string" format. In either case, the second SUBSET parameter is always an integer that indi- 
cates the number of key values you want dumped. 

BY KEY NUMBER 

The key number is the sequential number associated with each key value in a particular key. If the 
KEYSEQ command has listed key numbers that are out of sequence, you may want to dump only 
these values. Suppose that TESTFILE has out of sequence values, the following example runs 
KEYSEQ first and then runs KEYDUMP to dump the key values shown as out of sequence. (In 
order to see the last value in correct sequence, the key preceding the first key out of sequence is 
selected as the first key to dump.) 

> KS TESTFILE 

KEY VALUE # (FOR KEY VALUE OUT OF SEQUENCE) 




I ■ values used for SUBSET= of KE YD UMP 

8 

9 

TOTAL # OF KEY VALUES READ 14 

# OF KEY VALUES OUT OF KEY SEQUENCE ORDER^f) 

KEY FILE STRUCTURE DAMAGED, KSAM FILE HAS TO BE RELOADED 

>KD TESTFILE ;SUBSET=5 i 5 number of key values out of sequence (plus 1) 

"key preceding first key # out of sequence 

The following dump shows the last key value in sequence followed by the key values that are out 
of sequence: 

KEY REC.PTR. KEY BLOCK ADR . 

1st key out 
of sequence 



BY KEY VALUE 

The second version of SUBSET= specifies an actual key value followed by the number of key values. 
You need not specify the exact key value; it can be a value less than an actual Integer or Double 
type key value (approximate match) or only the first part of a Byte type key value (generic match). 
For example, suppose TESTFILE has an alternate key that contains names in alphabetic order and 
you want to look at the ten key values that start with "GI" or the next greater value. Specify the 
following command: 



0005 


3 




12(2) 


0008 


9 


18(5) 




0007 


4 


18 




0009 


7 


18 




0006 





18 





>KD TESTFILE ;SEQ=2 ;SUBSET="GP' ,10 



dump 1st 10 values starting with or 



1st alternate key greater than "GI" 
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The dump appears as follows: 



KEY 


REC.PTR. 


KEY BLOCK ADR. 


GIBBS 


3 


2(4) 


GILLESPIE 


12 


2 


GLADSTONE 


4 


2 


HERTZ 


8 


2 


HIGGINS 





8(3) 


JONES 


7 


16(4) 


LOOMIS 


13 


16 


MORRIS 


5 


16 


MYERS 


6 


16 


NOLAN 


1 


- 8 



SORTING DUMP BY RECORD POINTER 

If you use the SORT option of KEYDUMP, you must also specify FILE= filename, where the spec- 
ified file name is that of a disc file. (Note that you must not name an existing file; a new file is cre- 
ated for the dump.) In this case, you might also want to suppress the indention of the key block 
address levels. To do this, enter the following command: 



suppress key block address indentation 

> KD TESTFILE ;FILE=MYFILE ;SUBSET=-1 ,500 ;SORT ^ sort by record pointer 



£ 



-dump is sent to MYFILE, created with default values 

The resulting dump is sent to a disc file MYFILE, created with a default block size of 10 words, 
one record per key entry. The key entries are sorted by the pointers to the records in the data file. 
Indentation of the key block address is suppressed. The key values, record pointers, and key block 
addresses are not converted to ASCII but are dumped to the specified file in binary format. In case 
of a file with 500 or fewer key values, the entire file is dumped. 

The SORT option is useful if you want to look at key values in terms of the data records to which 
the key values point. For example, in order to determine whether any key values are missing, you 
can dump all the keys in a file using the SORT option, and compare the record numbers in each 
dump to make sure each record has the same number of key values pointing to it. 
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Displays information about the key file, and attempts recovery of a KSAM file in case of system 
failure when the file is open. 



>{£P INF °) [dereference] [;OFFLINE] [.RECOVER] 



KEYINFO performs two operations: it collects and displays information about the key file, and 
it takes steps to recover the KSAM file in case a system crash occurred when the file was open. The 
second operation is performed only after a system crash or if the RECOVER parameter is specified. 

The key information displayed by KEYINFO consists of: 

• Number of levels in key block structure: 

• Number of key blocks 

• Number of sectors per key block 

• Number of keys in root block 

• Number of keys in all blocks of the key file 

• Percent of each key block used 

• Largest key block address 

The crash recovery performed by KEYINFO depends on the type of damage to the file. 

• If MPE end-of-file does not match end-of-file for KSAM data file, KEYINFO resets the MPE 
end-of-file to match the KSAM end-of-file. 

• If key file contains values that point to records past the KSAM end-of-file, KEYINFO deletes 
these key values. 

• If the key file end-of-file marker does not match the actual end of the key file, KEYINFO cor- 
rects the key file end-of-file marker. 

• If records in the data file do not have associated key values in the key file, KEYINFO issues a 
warning that key values are missing. 

PARAMETERS 

filereference Actual file designator of the KSAM file; either the data file name or the 

key file name may be specified. The filereference can be a back refer- 
ence to a file named in an MPE -.FILE command. 

(Optional parameter if no parameters are specified.) 

Default: If omitted, the last file referenced is assumed. 
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OFFLINE 



Directs output to the line printer. An MPE :FILE command can be 
used to indicate a different output device or a particular line printer. 
(Optional parameter.) 



RECOVER 



Default: If omitted, output is sent to user's terminal. 

Forces KEYINFO to perform recovery procedures even though no 
system crash occurred. 



(Optional parameter.) 

Default: If omitted, recovery performed only if system crashed with 
file open. 



REQUESTING KEY FILE INFORMATION 

Information is displayed by KEYINFO for each key in the key file, in key order starting with the 
primary key. For example, request KEYINFO for the file DATAFIL which has three keys: 

>KI DATAFIL 



INFO FOP KEY 



# OF LEVELS OF B-TREE 

# OF KEY BLOCKS 

# OF SECTORS PER KEY BLOCK 

# OF KEYS IN ROOT KEY BLOCK 
(t OF KEYS IN B-TPEE 

% OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK ADDRESS 



1 

1 

9 
20 
20 
38. 4 

2 



INFO FOP KEY 



# OF LEVELS OF B-TRF.E 

# OF KEY BLOCKS 

# OF SECTORS PER KEY BLOCK 

# OF KEYS IN ROOT KEY BLOCK 

# OF KEYS IN B-TREE 

% OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK ADDRESS 



INFO FOP KEY 



# OF LEVELS OF B-TPEE 

# OF KEY BLOCKS 

# OF SECTORS PER KEY BLOCK 

« OF KEYS IN ROOT KEY BLOCK 

# OF KEYS IN B-TPEE 

% OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK ADDRESS 



1 
t 

a 

20 
20 

9.9 
10 



1 

1 

8 
20 
20 

13.8 
18 



>EXIT 



# OF LEVELS OF B-TREE - Key files are organized in a structure known as a "B-Tree". This 
structure may have one or more levels (for details refer to appendix B). The file DATAFIL has 
only one level. 
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# OF KEY BLOCKS - Key values are stored in blocks; this entry gives the total number of key 
blocks in the file. DATAFIL has only one key block. 

# OF SECTORS PER KEY BLOCK - A key block may require one or more 128-word sectors. 
DATAFIL uses eight sectors for its key block (the default value). 

# OF KEYS IN ROOT BLOCK - This specifies the number of key values stored in the root block 
(in this case the only block). If this number is equal to the key blocking factor (see KEY BF header 
in VERIFY output), then the next key block split will increase the number of levels in the B-Tree 
by one. DATAFIL has 20 key values in its root block, and the blocking factor allows 52, 202, or 
144 (see VERIFY printout below). 

> VERIFY DATAFIL 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?_2. 

KEY FILEsKEYFIL KEY FILE DEVICE=2 SIZE= 50 KEYS= 3 

FLAGWORDC000000)=RANDOM PRIMARY, FIRST REC0RD=0, PERMANENT 

KEY TY LENGTH LOC. D KEY BFv LEVEL LI , . . , „. , 

|g j |y 5 9 j blocking factor, keys/block 

2 B 2 31 Y 202 1 

3 B 6 33 Y 144 1 



# OF KEYS IN B-TREE - This is the total number of key values in the key file for each key. This 
number should be the same for each key and should also be the same as the number of active re- 
cords in the data file (to determine this, use the FCOPY command >FROM=DATAFIL;TO=$NULL 
;KEY=0. FCOPY is described later in this section). DATAFIL has 20 key values in each B-Tree, 
and this is the same number as the number of active data records (see FCOPY output below). 



:RUN FCOPY. PUB. SYS 

HP32212A.3.08 FILE COPIER (C) HEWLETT-PACKARD CO. 1978 

>FROM«DATAFIL;TQs$NULL;KEYsQ 

EOF FOUND IN FROMFILE AFTER RECORD 19-* records numbered from 

20 RECORDS PROCESSED #** ERRORS 



% OF KEY BLOCK UTILIZATION - Average percent of use of all key blocks (percent of use means 
how much of the block contains key values). Note that the root block of a multi-level tree is omitted 
from this average. For multi-level trees the percent is between 50% and 100%, for single-level trees 
between 0% and 100%. The higher the percentage, the faster the retrieval of data. But, also the high- 
er the percentage, the greater the chance of block splits when records are added. DA TAFIL uses 
38.4% for its primary key, d.9% and 13.87c each for its two alternate keys. 

THE LARGEST KEY BLOCK ADDRESS - This is the largest key block address found for each 
key. The key file end-of-file should never be less than the largest block address for the file plus the 
number of sectors per key block. The largest block address for DATAFIL is 18 (the largest block 
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address for DATAFIL is 18 (the largest block address of key 3). Since the number of sectors per 
block is 8, the key file end-of-file should be at least 26 (see VERIFY output below). 

WHICH C1=FILE INFO, 2sKSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3 



DATA FILE = 1 


DATAFIL 




VERSION: A. 2 


.1 










KEY CREATED*! 


292/' 


'78 


10; 


19: 7.4 


KEY ACCESS= 


107/'79 12: o: 2 


.9 




KEY CHANGED: 


93/' 


'79 


14: 


18: 7.6 


COUNT 


START: 


=292/'78 10:19:53 


.6 




DATA RECS = 






20 


DATA BLOCKS= 




19 


END BLK WDS= 




19 


DATA BLK SZ= 






19 


DATA REC SZ= 




38 


ACCFSSORS= 







FOPEN 






2 


FREAD 







FCLQSE 




2 


FREADDIR 









FREADC 







FREADBYKEY 







FREMOVE 









FSPACE 




57 


FFINDBYKEY 







FGETINFO 






2 


FGETKEYINFO 




I 


FREADLABEL 







FWRITELABEL 









FCHECK 







FFINDN 




3 


FWRITE 






20 


FUPDATE 







FPOINT 







FLOCK 









FUNLOCK 







FCONTROL 







FSETMODE 





















KEYBLK READ 






7 


KEYBLK WROTE 







KEYBLK SPLIT 







KEY FILE EOF 






y@ 


FREE KEY HD 







SYSTEM FAILURE 







MIN PRIME 






11 


MAX PRIME 




5 


RESET DATE 


67/ 


'79 


DATA FIXED 




/TRUE 


DATA B/F 




1 


TOTAL KEYS 




3 


FIRST PECNUM 









MIN PECSIZE 




38 









key file end-of-file for DATAFIL 

RECOVERING AFTER SYSTEM FAILURE 

KEYINFO only performs the recovery operations if there has been a system failure or if you spec- 
ify the RECOVER parameter. 

If there has been a system failure while the KSAM file is open for non-read access, a flag is set that 
prevents the file from being opened. Whenever this occurs, KEYINFO must be used in order to re- 
set this flag so that the file can be opened. KEYINFO also recovers from any damage done to the 
file as a result of the system failure. It resets end-of-file markers for both the data and key files, and 
deletes any key values that point to records beyond the data file end-of-file. It also stores in the key 
file the user, group, account, and home group of the user who runs KEYINFO to recover the file. 
(When there has been a system failure or when KEYINFO is run with the RECOVER option, the 
KSAM file is opened for exclusive access; otherwise it is opened for shared access.) 

When KEYINFO is run after a system failure, the SYSTEM FAILURE count displayed by option 3 
of VERIFY is incremented by 1. If there was no system failure but KEYINFO was run with the 
RECOVER option, this count is not incremented. 

When KEYINFO resets the "crash" flag, the date of this reset is saved and can be recovered through 
the VERIFY command, option 3 under the heading RESET DATE. Note that the NOCHECK op- 
tion of VERIFY allows that command to open a KSAM file for read-only access even if a system 
failure prevents the file from being opened for all other access. 

For example, assume a file TEST that was open when a system failure occurred. In this case, KEY- 
INFO must be run. Also, assume the following: 

• The data file end-of-file (at the end of the data) is beyond the MPE end-of-file (not yet written 
to file when system failed). 

• There are key values beyond the key file end-of-file (internal key file EOF). 

• There are data values with no associated key values. 
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Running KEYINFO will correct the end-of-file markers and, if any keys point to data records be- 
yond the data file end-of-file, it will delete these key values. KEYINFO cannot, however, restore 
missing key values. To do this, you must reload the file with FCOPY. To illustrate, KEYINFO op- 
erates as shown below: 



> KI TEST 
RECOVERY BEGINS 

DATA FILE EOF DAMAGED 

OATA FILE MPE EOF HAS BEEN RESET TO KSAM EOF 



reset end-of-file 
for data file 



INfO FOR KEY 



1 



* OF LEVELS OF 8-TREE 

* OF KEY BLOCKS 

* OF SECTORS PER KEY BLOCK 

t OF KEYS IN ROOT KEY BLOCK 

* OF KEYS IN B-TREE 

* OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK ADORESS 



INFO FOR KEY 



OF LEVELS OF B-TREE 

OF KEY BLOCKS 

OF SECTORS PER KEY rLOCK 

OF KEYS IN ROOT KEY BLOCK 

OF KEYS IN B-TREE 

OF KEY BLOCK UTILIZATION 




# of keys should 
match 



4ARNINGI THERE ARE SOmE RECORD (S> WITH KEY VALUE (S) MISSING 
OR KEY VALUE (S) POINTin© TO DATA RECORO BEYOND EOF 



<EY FILE EOF (INTERNAL) DAMAGED 

<EY FILE (INTERNAL)EOF HAS BEEN RESET 



reset key file end-of-file 



— KEY SEQUENCE 1 - 

4 OF INVALID KEY VALUES pELETEo 

KEY SEQUENCE 2 - 

* OF INVALID KEY VALUES DELETED 

RECOVERY ENDS 



10 
10 



keys pointing to non-existent 
data records are deleted 



*ARNINGI THERE ARE SOmE RECORD (S» WITH KEY VALUE (S) MISSING 
THE KSAM FILE HAS TO BE RELOADED 



In this case, the file must be reloaded in order to add the missing key values to the key file. For 
a full discussion of recovery procedures in case of system failure, including how to reload your file, 
refer to appendix E. 
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USING RECOVER OPTION 

Even if a system failure does not occur, you can run KEYINFO with the RECOVER option in order 
to check the file structure. 

The RECOVER option forces KEYINFO to correct any end-of-file inconsistency, including the key 
file end-of-file, and to delete any invalid key values. This option sets the RESET DATE field of the 
VERIFY output to the current date, and saves your user name, account, group, and home group, 
but does not increment the SYSTEM FAILURE count displayed by VERIFY. 

Note that checking each record and key in a file with a lot of data is very time consuming. Therefore, 
you should not use RECOVER unless it is necessary to reconstitute your file. 

For example, use KEYINFO with RECOVER to validate file TEST: 

> KI TEST; RECOVER 
RECOVERY BEGINS 



INFO FOR KEY 



# OF LEVELS OF B-TREE 

# OF KEY BLOCKS 

# OF SECTORS PER KEY BLOCK 

# OF KEYS IN ROOT KEY BLOCK 

# OF KEYS IN B-TREE 

% OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK ADDRESS 



1 
1 

8 

to 

10 

4, 
2 



KEY SEQUENCE 1 ■ 

# OF INVALID KEY VALUES DELETED 

RECOVERY ENDS 



If you now run VERIFY, using option 3, you will see that the date of recovery is displayed follow- 
ing the heading RESET DATE. 



>V 



WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3 



DATA FILE = 
KEY CREATED= 
KEY CHANGED= 
DATA RECS = 
DATA BLK SZ= 
FOPEN 
FPEADDIR 
FPEMOVE 
FGETINFO 
FWRITELABEL 
FWRITE 
FLOCK 
FSETMODE 
KEYBLK READ 
KEY FILE EOF 
MIN PRIME 
DATA FIXED 
FIRST RECNUM 



TEST VERSION= A. 2. 4 

86/'79 13:55:23.6 KEY ACCESS* 
114/'79 13:55:48.8 COUNT START: 



10 DATA BL0CKS= 
8 DATA REC SZ= 
2 FREAD 
FPEADC 
FSPACE 

2 FGETKEYINFO 
FCHECK 

10 FUPDATE 
FUNLOCK 


3 KEYBLK WROTE 
10 FREE KEY HD 

MAX PRIME 
TRUE DATA B/F 

MIN RECSIZE 



9 
16 


9 
1 




1 


9 
1 
2 



114/'79 14: li 
■ 96/'79 13:55; 
END BLK WDS= 
ACCESSORS= 
FCLOSE 
FREADBYKEY 
FFINDBYKEY 
FREADLABEL 
FFINDN 
FPOINT 
FCONTROL 

KEYBLK SPLIT 
SYSTEM FAILURE 
RESET DATE 
TOTAL KEYS 



14.9 

49.2 

8 

2 




1 








114/'79 

1 
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USING KSAMUTIL IN BATCH MODE 

A batch job can be developed on the text editor (EDITOR) and then executed with the MPE 
: STREAM command. In order to distinguish the MPE commands within a streamed batch job 
from those external to the job, an exclamation point (!) is used as the command prefix rather than 
a colon (:). KSAMUTIL commands have no command prefix when executed in a batch job. 

In the job illustrated in figure 2-1, the first step after job initialization with the ! JOB command is 
to purge all KSAM and non-KSAM files that will be created within the job. This insures that there 
are no files in the account with names duplicating files that will be created programmatically with 
the job. 

Following initialization, the first program in the job is run. Since this program uses a KSAM file, 
MANPN, this file is created with the KSAMUTIL BUILD command before the program is executed. 
Note that the program is purged immediately before calling BUILD to create it. This is done to 
make sure that no duplicate key or data file exists in the account. 

The newly created KSAM file is used in program MAN1, which was previously compiled and is input 
from the file CARDIN; output from the program goes to the file REPORT associated with the line 
printer. An !EOD command follows the program. If data is entered here rather than from the input 
file, then the !EOD follows the data. Any other programs in the job stream follow the !EOD each 
with its own terminating !EOD. The entire job is terminated by an !EOJ command. 

Figure 2-1 is an EDITOR listing of a job entered to a file through the EDITOR program. This 
job could also have been punched on cards or any other device that accepts jobs, but in that case, 
the standard command prefix, the colon (:), would be used. (Refer to the EDIT/3000 reference 
manual for instructions on using the EDITOR.) 

In order to run this job, you can enter the command: 

: STREAM filename 

where filename identifies the EDITOR file where the job was saved. 

Batch jobs need not be streamed, but can be entered entirely as a card deck or through some other 
input device. Streaming allows you to develop and execute the job interactively at your terminal. 
For a full discussion of using the :STREAM command to introduce jobs in a session, refer to the 
MPE Commands Reference Manual. 
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job 
initialization 



job 
introduction 



job name 



user 



L 




account 



program 



_JJOB BOMP,MGR.MANUF 
""iRUN KSAMUTIL 

PURGE MANONE 

PURGE MANTWO 

EXIT ~ 

•PURGE MANSHP 
r ! PURGE MANSAV 
~! COMMENT .. RUN MAN! TO 

fRUN KSAMUTIL. PUB. SYS 

PURG E MANPN purge key and data file before creation 

BUILD MANPN;p.EC=-256, 1,F,ASCII;DISC = 500;& 



purges KSAM files 

- purges non-KSAM files 

GENERATE PART NUMBER FILE, MANPN 



EXIT 

!FILE 

!FILE 



keyfile=manpnkey;key=b,24,i2;firstrec=i 

t 



cardin=#stdin 
report; dev=lp; cctl 

•TELLOP MAN! BEGINNING EXECUTION 

•RUN MAN 1- previously compiled program 

<DATA> 
JEOD 

*"< OTHER PROGRAMS IN BATCH STREAM > 
•!EOJ 



record in file 
numbered from 
1, not 



job 
termination 



Figure 2-1. EDITOR Listing of Job to be Streamed 
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FCOPY/3000 is the standard HP 3000 utility program that allows you to copy data from one file 
to another, creating a new KSAM file is desired, to copy selected data, to make multiple copies of 
the same file, or to display data in a variety of formats. With some exceptions, the same FCOPY 
functions used to copy other HP 3000 files can be used to copy KSAM files. 

Table 2-4 contains a summary of the FCOPY function parameters that apply to copying KSAM files. 
The function parameters: SKIPEOF, IGNERR, and SUBSET alone, are not included in this list since 
they are not applicable to KSAM files. Two functions are included that apply only to copying from 
KSAM files: these are KEY= and NO KSAM. Otherwise, this table includes all the standard FCOPY 
functions. Note that this summary is meant only to refresh your memory and that it assumes a 
knowledge of FCOPY. (For a complete description of FCOPY and its operation, refer to the FCOPY/ 
3000 reference manual.) 

RUNNING FCOPY 

The FCOPY utility program is executed by the MPE command: 

:RUN FCOPY.PUB.SYS 

Program FCOPY prompts for command input with a greater- than sign (>) in column 1 of the next 
line. You may then enter an FCOPY command in response to the prompt. If you are executing 
FCOPY in a batch job rather than in a session, you enter the command (omitting the prompt) in 
column 1 of the line following the :RUN FCOPY.PUB.SYS command. 

EXITING FROM FCOPY 

In order to terminate FCOPY and return to the MPE Operating System, enter the following 
command: 

>EXIT or >E 
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FROM COMMAND 

Copies data from one file to another. 

>FROM= [/romftte] ;TO= [tofile] [; function list] 

The FROM command specifies the file from which data is copied and the file to which it is copied. 
It optionally includes one or more function specifications in the functionlist parameter. 

PARAMETERS 

fromfile Specifies the file to be copied. For a KSAM file this should be the 

actual file designator. An asterisk (*), indicating the "from" file 
designated in the immediately preceding FCOPY command should 
not be used to copy KSAM files. If fromfile is omitted, the standard 
input device $STDIN is assumed. 

tofile Specifies the file to receive the data. For a KSAM file this should be 

the actual file designator. If tofile is specified as (dfile,kfile) where 
dfile is a data file name and kfile is a key file name, a new KSAM file 
is created with the same characteristics as the fromfile. The data and 
key values are copied from the existing file to the new file excluding 
any data records tagged for deletion. 

If tofile is omitted, the standard list device $STDLIST is assumed. 
Using this device as a "tofile" is a good way to display the contents 
of a KSAM file at your terminal during a session and on the line 
printer in a batch job. 

functionlist One or more keyword parameters separated by semicolons that specify 

particular FCOPY functions. (Refer to table 2-4 for a complete list.) 

KSAM OPTIONS 

Two keyboard options may be used with FCOPY to copy KSAM files: the KEY= option and the 
NO KSAM option. These two options are mutually exclusive; they cannot both be specified in the 
same FCOPY FROM command. When neither option is specified, the KSAM fromfile is copied to 
another file in primary key sequence. This is exactly like copying any HP 3000 file to another with 
FCOPY. 

Table 2-5 summarizes the results of using, or omitting, the KSAM options KEY= and NOKSAM. 

KEY= OPTION. KEY= specifies a key whose value determines the sequence in which the file is 
copied. The object of KEY= is a positive integer that identifies the key by its starting character 
location in the data file. The indicated key may be either the primary or an alternate key. If the 
object of KEY= is zero, then the file is copied in chronological sequence rather than in key sequence. 

If KEY= and NOKSAM are both omitted, the KSAM file is copied in primary key sequence. In this 
case and in the case where KEY= is specified, only active records, not those tagged for deletion are 
copied. 
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Table 2-4. FCOPY Functions with KSAM Files 



FUNCTIOM LIST ENTRY* 


ACTION PERFORMED 


;KEY=nn 


Copy active records from KSAM file in sequence by 
key located at nn; if omitted, copy file in primary 
key sequence; if nn is zero, copy file in chronological 
order. The KSAM EOF is used. 


;NOKSAM 


Copy all records, including deleted records, from data 
file of KSAM file to any other file. Copy is in chrono- 
logical sequence; records must be fixed length. The 
data file being copied is opened as an MPE file and the 
MPE end-of-file is used. Unless the TO file is an MPE 
file created with 1 user label, specify NOUSERLABELS. 


;NEW 


Copy active records and associated key values from 
KSAM file to new KSAM file specified as TO= 
(dfile,kfHe). 


|;EBCDICIN) 
|;BCDICIN 1 

j;EBCDICOim 
|;BCDICOUT J 


Translate copied data from EBCDIC or BCDIC code 
to ASCII. 

Translate copied data from ASCII code to EBCDIC 
or BCDIC. 


;UPSHIFT 

.-subsetJ?"^' 1 

1 ^pattern # j 
;SUBSET= [first-record] 


, [column ] 
.EXCLUDE] ] 

I ,#records 1 

1 : last-record [ 

_ _ 




Convert any copied lower-case characters to upper- 
case. 

Copy from data file only records containing speci- 
fied "string" or #pattem# starting search in specified 
column or column 1 . If EXCLUDE specified, copy 
all data file records except those containing "string" 
or #pattern# 

Copy from data file as many records as are specified 
in #records starting with first-record; or copy from 
first-record through last-record inclusive. If first- 
record omitted, start at first sequential record in 
file; if #records or last-record omitted, copy through 
last sequential record in file. 


;VERI FY [=#e/rors] 
;COMPARE[ = #erro/-s] 


Verify accuracy of copy where both files are on disc; 
terminate if terrors exceeded; 

Compare without copying the fromfile to the tofile; 
terminate if differences exceed terrors. Comparison 
applies only to KSAM data files. 


;OCTAL 

;HEX[; 

;CHAR 


[;CHAR] [;N 

CHAR] [;NOR 

f ; OCTAL \ 
j;HEX } 


DRECNUM] [;TITLE="f/f/e"l 
ECNUM] [;TITLE="f/W] 

[;NORECNUM] 

t;TITLE="f/f/e"] 


Display contents of "from" file as octal images on a 
word-by-word basis. 

Display contents of "from" file as hexadecimal 
images on a word-by-word basis. 

Display contents of "from" file as character images 
on a word-by-word basis. 


*IGNERR, SKIPEOF, and SUBSET without parameters do not apply to KSAM "from" files. 
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OPTION 



KEY= omitted 



KEY=n (n>0) 



KEY=0 



NOKSAM 



Table 2-5. KSAM Options of FCOPY 



RESULT 



Copy KSAM file in primary key sequence. 



Copy KSAM file in sequence by the key (primary or alternate) located starting 
at character n of each data record (counting from first character = 1 ). 



Copy KSAM file in chronological sequence (the sequence in which records were 
actually stored in the file); copy excludes records marked for deletion. 



Copy the data file of a KSAM file to any file in chronological sequence; copy 
includes records marked for deletion. 



NOKSAM OPTION. NOKSAM allows you to copy the data file of a KSAM file with fixed-length 
records to any MPE file, including KSAM files. All indicated records of the data file are copied, in- 
cluding those tagged for deletion. When you copy a file using the NOKSAM option, you should 
also specify the NOUSERLABELS option. The only exception to this rule is if the TO file is an 
MPE file that you have already created with one user label. 



USING FCOPY 

FCOPY is useful in order to compact a KSAM file that has many records tagged for deletion. When 
a file has been used for a period of time, changes and deletions may result in a high percentage of 
inactive records. In order to recover the space occupied by such records, you can copy the file to 
a new file with FCOPY. Since FCOPY copies only active records, records that are not tagged for 
deletion, the new KSAM file has no unused space embedded among the data records. 

FCOPY can also be used to recover records tagged for deletion in a KSAM file. The FCOPY 
NOKSAM option copies all records including those tagged for deletion. The first two characters 
of such records will contain the delete code rather than their original values, but otherwise are 
recovered intact. This can be a useful feature in order to recover records deleted by mistake. 

Another use of FCOPY is to reload data from a damaged file to a new file. This may be required 
as a result of a system failure. If you decide to reload a KSAM file following a system failure, you 
should first run the KEYINFO command of KSAMUTIL to reset the end-of-file markers and delete 
any invalid key values. If the file is still damaged and you choose to reload it, you should use 
FCOPY to transfer existing records to a new undamaged KSAM file. In this case, you use the 
KEY=0 option rather than the NOKSAM option, unless you want to keep all the deleted records 
or the key file was lost. 

FCOPY WITH NO OPTIONS. Assume a file named KSAMFILE created with one primary key, an 
integer located at character 21. Since many records were tagged for deletion in the file, it is time to 
copy the active records to a new file. You may either create a new KSAM file with the BUILD com- 
mand as shown in example 1, or use FCOPY to create the new KSAM file as shown in example 2. 
In either case, you should purge the original file (KSAMFILE in the examples) and then rename the 
new file (KSAMFIL2) with the data and key file names of the original file so that any programmatic 
references to the file need not be changed. 

You may also use FCOPY to create an empty KSAM file with all the characteristics of an existing 
file, but with no data. The method for doing this is shown in example 3. 
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1 . Create new file with BUILD : 

; RUN KSAMUTIL.PUB.SYS 

> BUILD K5AMFILS;KEYFILE=KFILg;KEY=I ,21 ,2 -> create "to " file 

> EXIT 

; RUN FCOPY. PUB. SYS 

> FP0M=KSAMFILE;T0=KSAMFIL2 -* copy in primary key sequence 

> EXIT 

{ RUN KSAMUTIL.PUB.SYS 

>PURGE KSAMFILE^ purge -p om » fu e a f ter copy 

KSAMFILE.KSAM.DATAMGT A KFILE PURGED 

>RENAME KSAMFIL2.. KSAMFILE ~K • , ,., .,. 7 , ,., 

^^»t»w^ „.^.. ~ „Z.,, ZT rename copied file with old file names 

>RENAME KFIL2.»KFILE J 



> EXIT 

2. Use FCOPY to create new file: 

: RUN FCOPY. PUB. SYS 

> FRQM=KSAMFILE;TP=(KSAMFIL2,KFILE2) 

> EXIT 

: RUN KSAMUTIL.PUB.SYS 

> PURGE KSAMFILE 

KSAMFILE.KSAM.DATAMGT & KFILE PURGED 

> RENAME KSAMFIL2, KSAMFILE 

> RENAME KFILE2rKFILE 

> EXIT 

• 

You may specify the ;NEW function in the FCOPY FROM command for purposes of document- 
ation. Its inclusion or omission does not affect the command in any way. 

This method not only creates the new KSAM file, but also copies all the data from the exising file 
to the new file (except records marked for deletion). Example 3 below, shows how you can create 
a KSAM file with exactly the same specifications as an existing file but with no data. 

3. Use FCOPY to build a new file with no data: 

: RUN FCOPY.PUB.SYS 

> FROM=KSAMFILE; TO=(KSAMFIL3,KFILE3); SUBSET=1,0 ^ copy records 

RECORDS PROCESSED *** ERRORS 

The new file, KSAMFIL3, is created with exactly the same specifications as the existing file 
KSAMFILE, but with no data. This is easier than building the file with the BUILD command, 
but should be used only if the new file is to have keys in the same position and the same length 
as the existing file. 

Following any of these operations, only active records are contained in the new KSAM files. These 
records are stored in primary key sequence in the data file; that is, the new chronological and the 
primary key sequences are the same. If you prefer to maintain the original chronological sequence, 
then you can use the KEY=0 option. 
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4. Use FCOPY to add data to an existing file: 

Before running FCOPY to add new records to a file that contains data, make sure that file 
(the TO file) is opened for either APPEND or INOUT access. Otherwise, FCOPY will open the 
TO file for write-only access causing the end-of-file to be reset to zero and any existing data to 
be lost. For example: 

:FILE A = KSAMFILE.OLD ;ACC = APPEND 

or 
ACC = INOUT 
:RUN FCOPY.PUB.SYS 
> FROM = NEWDATA ;TO = * A 

The data in the file NEWDATA is appended to the data in the existing file, KSAMFILE, in 
primary key sequence (the default) . 
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FCOPY WITH KEY = OPTIONS. 

1. Assume that a company's employee records have been maintained in sequence by social- 
security-number in a KSAM file, EMPLOY, but a new policy requires that they be maintained 
in sequence by employee number. FCOPY can be used to transfer the data to a new file, 
EMPLOY2, in which all employees are re-ordered by their unique employee numbers. 

Assume EMPLOY was created with the following command: 

:RUN KSAMUTIL.PUB.SYS 

>BUILD EMPLOY;REC=3000JKEYFILE=EMPKEY;« 

> KEY=B* 3* 1 1 i & -* primary key (social-security-number) 

* KEY=B>14.»5>4 -* alternate key (employee number) 

> KEY=Bj 1 9> 3<Sf > DUP- alternate key (name) 

>EXIT 

Before copying and resequencing file EMPLOY, a new KSAM file is built: 

:RUN KSAMUTIL.PUB.SYS 

>BUILD EMPLOY2;REC=3000;KEYFILE=EMPKEY2;& 

> KEY=B.» 1 i\> 5 i &- primary key (employee number) 

> KEY=B, 1 9, 30* * DUP- alternate key (name) 

>EXIT 

There is no need for the new key file to retain the same structure as the key file of the copied 
file. The primary key in EMPLOY has been dropped from EMPLOY2; although the social- 
security-number remains in the data file, it is no longer a key. An alternate key in EMPLOY, 
the employee's identification number, is the primary key in EMPLOY2. 

Once the new KSAM file has been created, you can copy the old file EMPLOY to the new file 
EMPLOY2 in the new sequence: 

:run fcopy. pub. sys 
>fpom=employ;to=employs;key=i h 

>EXIT 



-column number of key used to sequence EMPLOY2 



To avoid changing programs that reference the file EMPLOY, you can rename EMPLOY2 with 
the name EMPLOY, first purging the old file EMPLOY: 

:RUN KSAMUTIL.PUB.SYS 

>°URGE EMPLOY 

KSAMFILE EMPLOY. KSAM. DA TAMGT * EMPKEY PURGED 

>RENAME EMPL0Y2, EMPLOY- • rename data file 

>RENAME EMPKEY2, EMPKEY- rename key file 

>EXIT 
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2. Another use of FCOPY is to copy a selected portion of one KSAM file to another. For 
example, using the same file EMPLOY used in previous examples, you can copy all the 
employee records whose last names begin with the letter A into a new file sequenced by 
employee name: 

:PUN KSAMUTIL.PTJB.SYS 

>BUILD EKPL0YA;KEYFILE=AKEYJKEY = B,19,3"!.. ; DU ra 

>EXIT 

:run fco^y.piib.sys 
>fo.om=em°loy;to=em t5 loya;key=19; SUBSET="A ,, j 19 

>EXIT 

The new file EMPLOY is sequenced by the key starting in column 19 (employee name) and 
only contains records for employees whose last names start with A. 

3. If you want to copy the KSAM file in chronological sequence, you can use the KEY=0 option. 
Since this option copies only active records, it can be used to compact a file in which many 
records are tagged for deletion while retaining the chronological order in which the file was 
created. It is also the preferred option for reloading a KSAM file after a system failure. 

Assume the new file EMPLOYX has the identical structure to the file EMPLOY used in the 
previous examples: 

:PTJN FCOPY. ottb .SYS 
>FROM=EMPLOY; T0=EMOL0YX; KEY=0 
>EXIT 

The new file is identical in its chronological sequence to the old file, but contains only active 
records. 

4. To find out how many records are currently active in a KSAM file, you can use FCOPY as 
follows : 

:RUNFCOPY.PUB.SYS 

> FROM=KSAMFILE ;TO=$NULL 

N RECORDS PROCESSED *** ERRORS (where N is the number of active records 

in the KSAM file) 
>EXIT 

Only the active records (those not marked for deletion) will be listed as present in the file. 
(You can also calculate the number of active records by looking at the VERIFY listing, option 
3, and subtracting the number of FREMOVEs from the FWRITES.) 

FCOPY WITH NOKSAM OPTION. 

1. Using NOKSAM, you can copy the data file of a KSAM file to another file. The records are 
copied in chronological sequence. Since NOKSAM copies records marked for deletion as well 
as active records, it provides a method for recovering the data in any records marked for 
deletion. For example, if certain records in file EMPLOY were incorrectly marked for 
deletion, the NOKSAM option could be used to copy the entire data file to a new file includ- 
ing the inactive records. 

Using the SUBSET parameter of FCOPY, you can copy only those records marked for deletion. 
In the following example, all deleted records are listed on the line printer: 
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/pattern of all 1 's in 1st 2 characters 



:FILE X;DEV=LP i 

:RUN FCOPY.^UB.SYS L 

>FR0M=EMPL0Y;T0 = *X;SU3SET = #X377., %377'f, I 7NOKSAM; OCTAL; CHAR; NOPECN'JM; * 
>TITLE="RECOPDS DELETED FROM THE FILE, EMPLOY" 



7Z 



When records are deleted from a KSAM data file, a pattern of all l's is written to the first two 
characters of the deleted record. (In each character this pattern can be represented as the 
octal value %377.) If you want to be able to recover key data from deleted records in this 
manner, you should avoid placing key data in the first two characters of a data record. 

Note that you should not use the NOKSAM option to copy a KSAM file with variable-length re- 
cords to another KSAM file. Also, if NOKSAM must be used to reload a file after a system crash 
(for instance, because the key file was lost), you should use the SUBSET option to copy only valid 
records. Normally, you use the KEY=0 option to reload KSAM files after a system failure. 

(Refer to appendix E, Recovery From System Failure, for a full discussion of using FCOPY to re- 
load a KSAM file following a system failure.) 



DISPLAY COPIED FILES ON $STDLIST. When you omit the "to" file from the TO= specifica- 
tion, the standard output device is assumed. This allows you to list the contents of the KSAM file 
at your terminal in a session or on the line printer in a job. 

Assume the file JNAMES with a primary key (last name) starting in character 11 and three alternate 
keys: a phone number starting in character 21, a city name starting in character 53, and a zip code 
starting in character 67. 

1. If KEY= is omitted, the file is listed in primary key order: 

>FR0M= JNAMES ;T0=) 



JEANNE 


r^ALOGICAL 


226-3295 


4942 


COUSIN CT 


SUNNYVALE 


95054 


^OLLY 


CHROMATIC 


267-141 3 


1 148 


COLORFUL CT 


SAN JOSE 


95030 


ANNA 


FORA 


253-5246 


9283 


TROCHAIC TRAIL 


SAN JOSE 


95131 


ANNE 


HOWE 


372-4328 


6547 


EXU3ERANCE WY 


CAMPBELL 


951 1 2 


HY 


KUVERSE 


267-8961 


651 


LOTUS BLOSSOM WY 


SAN JOSE 


95136 


ANNA 


LOGUE 


224-8934 


1 70 7 


INVERSE WY 


MOUNTAIN VIEW 


955)51 


ARTHUR 


i 


MOMITER 


443-5346 


1 55.4 


MERCURY ST 


MIL°ITAS 


94173 


CLARA 




NETTE 


243-4493 


2667 


GOODMAN DR 


ALVISO 


95143 


RHEA 




PREYSELLE 


365-8551 


10879 


REVIEW ROAD 


SAN JOSE 


95070 


KTlRT 




REMARQUE 


243-1043 


34 


BRIEF ST 


MILPITAS 


94062 


MIKE 




ROMETER 


269-1712 


1631 


MACHINIST DR 


SUNNYVALE 


951 12 


TRUDY 




^TEKTIFF 


255-1005 


I 71 55 


POIROT PL 


CAMPBELL 


9512 1 


EOF FO 


UNI 


) IN FROMFILE AFTER RECORD 


1 1 
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ascending order by primary key 



Use SUBSET to list selected portions of the file, for example, to list the first two records in 
primary key sequence: 



> FR0M=JNAMESJT0=JKEY=1 1 J5UBSET=0 J S 

JEANNE ALOGICAL 226-0295 4942 COUSIN CT 

DOLLY CHROMATIC 267-1413 1148 COLORFUL CT 

2 PECORDS PROCESSED *** ERRORS 



SUNNYVALE 
SAN JOSE 



95054 

95030 
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2. If KEY="primary key location", the file is listed in primary key order: 



>frqm=jnames;tq=;key=i i 



JEANNE 


ALOGICAL 


226-0295 


4942 


COUSIN CT 


SUNNYVALE 


95054 


POLLY 


CHROMATIC 


267-1413 


1 1 48 


COLORFUL CT 


SAN JOSE 


95030 


ANNA 


FORA 


253-5246 


9283 


TROCHAIC TRAIL 


SAN JOSE 


95131 


ANNE 


HOWE 


372-4328 


6547 


EXUBERANCE WY 


CAMPBELL 


951 12 


HY 


KUVERSE 


267-8961 


650 


LOTUS BLOSSOM WY 


SAN JOSE 


95136 


ANNA 


LOGUE 


224-8934 


1707 


INVERSE WY 


MOUNTAIN VIEW 


95051 


ARTHUR 


MOM ITER 


443-5346 


1554 


MERCURY ST 


MILPITAS 


94173 


CLARA 


NETTE 


243-4493 


2667 


GOODMAN DR 


ALVISO 


95143 


RHEA 


PREYSELLE 


365-8551 


10879 


REVIEW ROAD 


SAN JOSE 


95070 


KURT 


REMARQUE 


243-1043 


34 


BRIEF ST 


MILPITAS 


94062 


MIKE 


ROMETER 


269-1712 


1681 


MACHINIST DR 


SUNNYVALE 


95112 


TRUDY 


.TEKTIFF 


255-1005 


17155 


POIROT PL 


CAMPBELL 


95121 


EOF FOUND 


/IN FROMFILE AFTER RECORD 


1 1 
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byte location 11 (same sequence as previous example) 



3. If KEY= "alternate key location", the file is listed in sequence by that key: 



>FROM= JMAMES; TO=; KEY=67 



KURT 


REMAROUE 


243-1043 


34 


BRIEF ST 


ARTHUR 


MOM ITER 


443-5346 


1554 


MERCURY ST 


POLLY 


CHROMATIC 


267-1413 


1 148 


COLORFUL CT 


ANNA 


LOGUE 


224-8934 


1707 


INVERSE WY 


JEANNE 


ALOGICAL 


226-0295 


4942 


COUSIN CT 


RHEA 


PREYSELLE 


365-8551 


10879 


REVIEW ROAD 


ANNE 


HOWE 


372-4328 


6547 


EXUBERANCE WY 


MIKE 


ROMETER 


269-1712 


1681 


MACHINIST DR 


TRUDY 


TEKTIFF 


255-1005 


17155 


POIROT PL 


ANNA 


FORA 


253-5246 


9283 


TROCHAIC TRAIL 


HY 


KUVERSE 


267-8961 


650 


LOTUS BLOSSOM WY 


CLARA 


NETTE 


243-4493 


2667 


GOODMAN DR 


EOF FOUND 


IN FROMFILE AFTER RECORD 


1 1 



MILPITAS 
MILPITAS 
SAN JOSE 
MOUNTAIN VIEW 
SUNNYVALE 

SAN JOSE 

CAMPBELL 
SUNNYVALE 
CAMPBELL 
SAN JOSE 
SAN JOSE 
ALVISO 
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output in ascending order - 
by key in byte location 67 ■ 



94062 
94173 
95030 
95051 
95054 
95070 
951 12 
95112 
95121 
95131 
95136 
95143 



A 



Use SUBSET= to list all the records with the characters "SUNNYVALE" starting in column 53; 
sequence is by alternate key in location 67: 



>FR0M= JNAMES^ TO = ; KEY=67; SUBSET = " SUNNYVALE", 53 



JEANNE ALOGICAL 226-0295 4942 COUSIN CT 
MIKE ROMETER 269-1712 1681 MACHINIST 
EOF FOUND IN FROMFILE AFTER RECORD 1 I 



DR 



SUNNYVALE 
SUNNYVALE 



95054 
951 12 



2 RECORDS PROCESSED *** ERRORS 
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Another example using SUBSET= lists five records starting with the fourth record; sequence 

is by alternate key in location 67 : , , , . „ 

/ records numbered from 



>FR0M=JNAMES;T0 = ;KEY=67JSUBSET=3.>5 



ANNA 


LOGUE 


224- 


-8934 


170 7 


INVERSE WY 


JEANNE 


ALOGICAL 


226- 


-0295 


4942 


COUSIN CT 


RHEA 


PREYSELLE 


365- 


-8551 


10789 


REVIEW ROAD 


ANNE 


HOWE 


372- 


-4328 


6547 


EXUBERANCE WY 


MIKE 


ROMETER 


269- 


-1712 


168 1 


MACHINIST DR 



5 RECORDS PROCESSED *** ERRORS 
4. If KEY=0, the file is copied in chronological order: 



MOUNTAIN VIEW 95051 

SUNNYVALE 9 50 54 

SAN JOSE 95070 

CAMPBELL 95112 

SUNNYVALE 95112 



>frqm=jnames;tq=;key = 



ARTHUR 


MOM ITER 


443-5346 


1554 


MERCURY ST 


MILPITAS 


94173 


TRUDY 


TEKTIFF 


255-1005 


1 7155 


POIROT PL 


CAMPBELL 


95121 


ANNA 


LOGUE 


224-8934 


1707 


INVERSE WY 


MOUNTAIN VIEW 


95051 


CLARA 


NETTE 


243-4493 


2667 


GOODMAN DR 


ALVISO 


95143 


ANNE 


HOWE 


372-4328 


6547 


EXUBERANCE WY 


CAMPBELL 


951 12 


JEANNE 


ALOGICAL 


226-0295 


4942 


COUSIN CT 


SUNNYVALE 


95054 


HY 


KUVERSE 


267-8961 


650 


LOTUS BLOSSOM WY 


SAN JOSE 


95136 


MIKE 


ROMETER 


269-1712 


1681 


MACHINIST DR 


SUNNYVALE 


951 12 


ANNA 


FORA 


253-5246 


9283 


TROCHAIC TRAIL 


SAN JOSE 


95131 


POLLY 


CHROMATIC 


267-1413 


1 148 


COLORFUL CT 


SAN JOSE 


95030 


RHEA 


PREYSELLE 


365-8551 


10879 


REVIEW ROAD 


SAN JOSE 


95070 


KURT 


REMARQUE 


243-1043 


34 


BRIEF ST 


MILPITAS 


940 62 


EOF FOUND 


IN FROMFILE AFTER RECORD 


1 1 
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:STORE AND :RESTORE COMMANDS 

The : STORE and : RESTORE commands are used primarily to provide back-up for user disc files. 
The file or set of files is copied to magnetic tape or serial disc by the : STORE command in a special 
format that permits the serial device to be read back onto disc with the : RESTORE command. The 
use of these two commands for KSAM files is identical to their use with any HP 3000 files. (Refer to 
the MPE Commands Reference Manual for a complete description of the : STORE and : RESTORE 
commands.) 



STORE 



Stores KSAM file on magnetic tape or serial disc. 



: STORE filereferencel,filereference2 [, 
[;SHOW] [;FlLES=max files] 



,] ; storefile 



This command is used to store one or more disc files onto magnetic tape or serial disc. When used 
to store KSAM files, both the data file and the key file must be specified. 



PARAMETERS 



filereferencel 



filereference2 



storefile 



SHOW 



Actual file designator of data file; specified in the following format: 
filename [/lockword] [.groupname [.accountname] ] 

where each subparameter is a name consisting of from 1 to 8 alpha- 
numeric characters beginning with a letter. 

(Required parameter for KSAM files.) 

Actual file designator of key file; specified in exactly the same format 
as filereferencel. 

(Required parameter for KSAM files.) 

Name of destination device file onto which the stored files are writ- 
en. This can be any magnetic tape or serial disc file from the output 
set. This file must be referenced in the back-reference (*) format; 
this format references a previous : FILE command that identifies the 
file as a magnetic tape or serial disc file. 

(Required parameter.) 

Request to list names of file stored. If SHOW is omitted, total number 
of files stored, names of files not stored, and number of files not 
stored are listed. 

(Optional parameter.) 
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FlLES=maxfiles Maximum number of files that may be stored. If omitted, 4000 is 

specified by default. 

(Optional parameter.) 

USING THE :STORE COMMAND 

Before issuing a : STORE command, you must identify the store file as a magnetic tape or as a serial 
disc with the :FILE command using the following format: 

:FILE formaldesignator [=filereference] ;DEV=dey/ce 

The device parameter must indicate the device class name or logical unit number of a magnetic tape 
or serial disc unit. All other parameters for storefile are supplied by the : STORE command executor; 
if you attempt to supply any of these yourself, MPE rejects the : STORE command. 

If you press the BREAK key during the store operation, the operation stops after storing the cur- 
rent file and further output is suppressed. 

For example, to copy KSAM file KSAMDATA to a magnetic tape file named SAVEFILE 

: FILE T=SAVEFILE;DEV=TAPE 

: STORE KSAMDATA,KSAMKEY; *T 

t t 

data file key file 

Note that both the data and key file must be specified in order to store the entire KSAM file. 

If you want to copy this same file to a serial disc, use the following command sequence: 

: FILE SD=SAVEFILE; DEV=SDISC 
: STORE KSAMDATA, KSAMKEY; *SD 
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Restores KSAM file from magnetic tape or serial disc. 



RESTORE 



i;DKv-d*nricf-j nsiiow] [;Fii,ESTnaxfiieai 

Restores to disc, one or more files stored off-line to magnetic tape or serial disc by the : STORE 
command. To restore a KSAM file, both the data file and the key file names must be specified. 



PARAMETERS 

restorefile 



filereferencel 



filereference2 



KEEP 



DEV=device 



Name of magnetic tape or serial disc file on which files to be re- 
trieved now reside. This file must be referenced in the back-refer- 
ence (*) format; this format references a previous :FILE command 
that defines the file as a magnetic tape or serial disc file. A message 
is output to the Console Operator requesting him to mount the 
magnetic tape or serial disc platter identified by the filereference 
parameter in the : FILE command, and allocate the tape unit or 
disc platter to you. 

(Required parameter.) 

Actual file designator identifying the KSAM data file, specified in the 
format: 

filename [/lockword] [.groupname [.accountname] ] 

where each subparameter is a name consisting of from 1 to 8 alpha- 
numeric characters beginning with a letter. 

(Required for KSAM files.) 

Actual file designator identifying the KSAM key file, specified in the 
same format as filereferencel. 

(Required for KSAM files.) 

Specification that if a file referenced in the : RESTORE command 
currently exists on disc, the file on disc is kept and the corresponding 
file on tape or serial disc is not copied into the system. If KEEP is 
omitted, and an identically-named file exists in the system, that file 
is replaced with the one on the tape or serial disc. If KEEP is omitted, 
and a file on tape or serial disc is eligible for restoring and a file of the 
same name exists on disc, and this disc file is busy, the disc file is kept 
and the tape or serial disc file is not restored. 

(Optional parameter.) 

Device class name or logical number of device on which files are to be 
restored. (This name is also written on the label of each file restored.) 
If you omit this parameter, MPE attempts to replace the files on a de- 
vice of the same class (or logical device number) as that of the device 
on which the file was created. If this attempt fails, perhaps because 
the device class specified does not exist or the tape or serial disc was 
created on a previous version of this computer, MPE attempts to 
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replace each file on a disc of the same type (fixed or moving -head) 
and subtype as that on which it was created. If this fails, MPE attempts 
to restore the file to a device of class name DISC. If this fails, the file 
is not restored. If the KSAM file was created with the data file and the 
key file on different devices, then RESTORE twice using different 
DEV=device in each RESTORE. 

(Optional parameter.) 

SHOW Request to list names of restored files. If you omit SHOW, only total 

number of files restored, list of files not restored (and the reason each 
was not restored), and count of files not restored, are listed. 

(Optional parameter.) 

FlL.ES=maxfiles Maximum number of files that may be restored. If omitted, 4000 is 

assigned by default. 

(Optional parameter.) 

USING THE iRESTORE COMMAND 

Before issuing a -.RESTORE command you must identify tape file as a magnetic tape or serial disc 
file with the :FILE command: 

:FILE formaldesignator [=filereference] ;DE\=device 

The device parameter must indicate the device class name or logical unit number of a magnetic tape 
or a serial disc unit. No other parameters than these may be supplied. If you attempt to supply 
more, the : RESTORE command is rejected. 

To retrieve from the magnetic tape file SAVEFILE, the KSAM file KSAMDATA that includes data 
file (KSAMDATA) and key file (KSAMKEY): 

: FILE T=SAVEFILE;DEV=TAPE 

: RESTORE *T;KSAMDATA,KSAMKEY;KEEP;DEV=DISC;SHOW 
To retrieve this same file from the serial disc STORDISC, enter the commands: 

: FILE SD=STORDISC; DEV=SDISC 

: RESTORE*SD; KSAMDATA. KSAMKEY: KEEP; DEV=DISC; SHOW 

Note that both the data file and the key file must be specified in order to restore the entire KSAM 
file. 

If the KSAM file currently saved on magnetic tape or serial disc was originally created with the 
data file resident on one device and the key file resident on a different device, then this capabil- 
ity can be retained only if you RESTORE twice using different DEV= specifications in each 
command. 

For example: 

:FILET;DEV=TAPE 



RESTORE *T; KSAMDATA; DEV=DISCONE 



RESTORE *T;KSAMKEY;DEV=DISCTWO 



Upon successful completion, KSAMDATA will be restored from tape file T to a device class identi- 
fied as DISCONE, and KSAMKEY will be restored from tape file T to a device class identified as 
DISCTWO. You would do this only in the case where the file was originally created using the 
BUILD command specification DEV=DISCONE for the data file, and KEYDEV=DISCTWO for the 
key file. 
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USING KSAM FILES IN COBOL 

PROGRAMS 



SECTION 



OVERVIEW 



KSAM files are accessed from COBOL programs through calls to a set of procedures. These proce- 
dures allow you to open, open for shared access, write records to, read records from, lock, unlock, 
update, position, and close a KSAM file. (Refer to table 3-1 for a list of the procedures and their 
associated functions.) The COBOL procedures provided with KSAM/3000 correspond to the 
INDEXED I-O module statements in COBOL 74. 

Note: The following applies when using KSAM with COBOL. 

• The KSAM file must be created with KSAMUTIL's > BUILD command. 

• To access a KSAM file in chronological order, the KSAM file must be copied to a non-KSAM 
file. 

• KSAM permits duplicate primary keys as an extension to the ANSII standards. 

In HP COBOL/3000, the procedures that are used to access KSAM files differ in form from the 
COBOL input/output statements used to access non-KSAM files. The KSAM interface procedures 
use parameters for information that would otherwise be specified in the FILE-CONTROL para- 
graph and the FD entry of the DATA DIVISION. These parameters are themselves defined in the 
WORKING-STORAGE section of the DATA DIVISION. The main restriction on the KSAM inter- 
face call parameters is that they must start on word boundaries. 
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Table 3-1. KSAM Procedures for COBOL Interface 



PROCEDURE 
NAME 


PARAMETERS 


FUNCTION 


PAGE 


CKCLOSE 


filetable 
status 


Terminates processing of KSAM file identified by 
filetable. 


3-12 


CKDELETE 


filetable 
status 


Logically removes record from KSAM file; deleted 
record is identified by previous read. 


3-13 


CKERROR 


status, 
result 


Converts numeric value returned in status to char- 
acter string result. 


3-17 


CKLOCK 


filetable 

status 

lockcond 


Dynamically locks file opened for shared access, 
conditionally depending on lockcond. 


3-18 


CKOPEN 


filetable 
status 


Initiates processing of file named in filetable; 
returns file number to first word of filetable. 


3-20 


CKOPENSHR 


filetable 
status 


Initiates processing with dynamic locking and shared 
access of file named in filetable. 


3-25 


CKREAD 


filetable 
status 
record 
recordsize 


Reads next sequential record from KSAM file iden- 
tified by filetable into record. 


3-26 


CKREADBYKEY 


filetable 

status 

record 

key 

keyloc 

recordsize 


Reads into record first record with a key in location 
keyloc whose value matches that of key, from KSAM 
file identified by filetable. 


3-29 


CKREWRITE 


filetable 
status 
record 
recordsize 


Replaces last sequential record read by CKREAD, 
or replaces record whose primary key matches the 
value of key item in record, with the contents of 
record. 


3-32 


CKSTART 


filetable 

status 

relop 

key 

keyloc 

keylength 


Positions record pointer in preparation for a sequen- 
tial read to the first record with a key in location 
keyloc whose value has the relation relop to the 
value of key. 


3-36 


CKUNLOCK 


filetable 
status 


Unlocks file dynamically locked by CKLOCK. 


3-40 


CKWRITE 


filetable 
status 
record 
recordsize 


Writes record of length recordsize from record to a 
KSAM file identified by filetable. 


3-42 
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CALLING A KSAM PROCEDURE 



The KSAM interface procedures (refer to table 3-1 for a complete list) are called using a CALL 
statement of of the following general form: 

CALL "name" USING filetable,status[,parameter[, . . .] ] 

Where: 

"name'''' identifies the procedure to which control is transferred. 

file table an 8- word table that identifies the file by name and in which access 

mode and input-output type are specified, and to which is returned 
the file number on open, and a code identifying the previous operation. 

status one word to which a two-character code is returned that indicates the 

status of the input/output operation performed on the file by the called 
procedure. 

parameter one or more parameters, depending on the particular procedure called, 

that further define operations to be performed on the file. 

The first two parameters, filetable and status, are included in every KSAM procedure call except 
CKERROR; other parameters may be specified depending on the particular procedure. If a param- 
eter is included in the procedure format, then it must be included in the procedure call. All param- 
eters are required. 

Another characteristic of KSAM procedure call parameters is that they must always start on a word 
boundary. In order to assure this, the parameters should be defined in the WORKING-STORAGE 
SECTION as 01 record items, 77 level elementary items, or else the SYNCHRONIZED clause 
should be included in their definition. 

A literal value cannot be used as a parameter to these procedures. Any value assigned to a data 
item used as a parameter is passed to the procedure, but a literal value causes an error. 

Depending on the procedure, certain data items may be assigned values as a result of executing the 
procedure. 



NOTE 

There are no COBOL procedures to read a KSAM file in chrono- 
logical order or to access a record by its chronological record 
number. (Chronological order is the order in which the data rec- 
ords were written to the file.) 



3-3 



FILETABLE PARAMETER 



The first parameter in every KSAM procedure call must be file table, a table describing the file and 
its access. This table is defined in the WORKING-STORAGE SECTION of the COBOL program. 
It requires eight words as illustrated in Figure 3-1. 



Word 
1 
2 
3 
4 
5 
6 
7 
8 



filenumber 



filename (8 characters) 



input-output type 



access mode 



lock/unlock 



previous operation 



Figure 3-1. Filetable Structure 



filenumber 



filename 



input-output type 



access mode 



A number identifying the file returned by the CKOPEN procedure 
after the file named in words 2-5 has been successfully opened. After 
the file is closed by CKCLOSE, filenumber is reset to 0. (This number 
should be set to zero when the file table is initially defined.) It must 
be defined as a COMPUTATIONAL item. 

The name of the KSAM file. This name is the actual designator 
assigned to the file when it is created with the KSAMUTIL BUILD 
command; filename may be a formal designator if it is equated to 
the actual designator in a : FILE command. 

A code that limits the file access to input only, output only, or allows 
both input and output: 

= input only 

1 = output only 

2 = input-output 

It must be defined as a COMPUTATIONAL item. 

A code that indicates how the file will be processed: sequentially only, 
randomly only, or either (dynamically): 

= sequential only 

1 = random only 

2 = dynamic (sequential or random) 

It must be defined as a COMPUTATIONAL item. 
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FILETABLE 



previous operation 



A code in the right byte of word 8 of the file table indicating the 
previous successful operation : 

= previous operation unsuccessful or there has been no previous 

operation on this file 

1 = CKOPEN successful 

2 = CKSTART successful 

3 = CKREAD successful 

4 = CKREADBYKEY successful 

5 = CKDELETE successful 

6 = CKWRITE successful 

7 = CKREWRITE successful 

8 = CKCLOSE successful 

9 = CKOPENSHR 

This field should be set to zero when the file table is initially defined 
and thereafter should not be altered by the programmer. It must be 
defined as a COMPUTATIONAL item. 



lock/unlock 



A code in the left byte of word 8 of the file table that indicates 
whether a CKLOCK or CKUNLOCK has been performed success- 
fully since the operation specified in previous operation: 

10 = CKLOCK successful 

11 = CKUNLOCK successful 



EXAMPLE 

A sample file table definition might be: 
WORKING-STORAGE SECTION. 



01 



KSAMFILE. 


02 


FILENUMBER 


02 


FILENAME 


02 


I-O-TYPE 


02 


A-MODE 


02 


PREV-OP 



PIC S9(4) COMP VALUE 0. 
PIC X(8) VALUE "KSAMFILE' 
PIC S9(4) COMP VALUE 0. 
PIC S9(4) COMP VALUE 0. 
PIC S9(4) COMP VALUE 0. 



The file table identifies a file created with the name KSAMFILE as a file to be opened for sequential 
input only. The values of I-O-TYPE and A-MODE can be changed following a call to CKCLOSE for 
the file. 
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STATUS PARAMETER 



The status parameter is a two-character item to which the status of the input-output operation is 
returned. It is always the second parameter in a KSAM procedure call. The status parameter must 
be defined in the WORKING-STORAGE SECTION of the COBOL program. 

Status consists of two separate characters: the left character is known as status-key-1, and the right 
is known as status-key-2. 



/— 


— left character k, — 


— right character — 


\ 




"status-key-1" 


"status-key-2" 







status word 



The possible combinations of the left and right characters of parameter status are shown in Table 
3-2. The values of status-key-2 (the right character) shown in the table are the only valid values 
for status-key-2. 



Table 3-2. Valid status Parameter Character Combinations 



If left character of status 
(status-key-1 ) equals: 


Then right character of status 
(status-key-2) may equal: 


"0" (successful completion) 


"0" (no further information) 


"2" (duplicate key) 


"1" (at end) 


"0" (no further information) 


"2" (invalid key) 


"1" (sequence error) 


'"2" (duplicate key) 


"3" (no record found) 


"A" (boundary violation) 


"3" (request denied) 


"0" (lock denied) 


"1" (unlock denied) 


"9" (file system error) 


"n" where n is the MPE file system 
error code. 



Combining status-key-1 with status-key-2, the following values may be returned to the status param- 
eter as a whole: 



If status = "00' 



'02" 



Successful completion — 

The current input/output operation was completed successfully; no 
duplicate keys were read or written. 

Successful completion; Duplicate key — 

For a CKREAD or a CKREADBYKEY call, the current alternate key 
has the same value as the equivalent key in the sequentially following 
record; duplicate keys are allowed for the key. For a CKWRITE or 
CKRE WRITE call, the record just written created a duplicate key 
value for at least one alternate key for which duplicates are allowed. 
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MAY 1981 



STATUS 



If status = "10" At End condition — 

In a sequential read using CKREAD, no next logical record was in the 

me. 

= "21" Invalid key; Sequence error — 

A call to CKWRITE attempted to write a record with a key that is not 
in sequentially ascending order, to a file opened for sequential access. 
A call to CKREWRITE was attempted but the primary key value was 
changed by the program since the previous successful call to CKREAD. 

= "22" Invalid key ; Duplicate key — 

An attempt was made to write or rewrite a record with CKWRITE or 
CKREWRITE and the record would create a duplicate key value for a 
key where duplicates are prohibited. 

= "23" Invalid key; No record found — 

An attempt was made with CKSTART or CKREADBYKEY to access 
a record identified by key, but no record is found with the specified 
key value at the specified location. 

= "24" Invalid key; Boundary violation — 

An attempt was made with a call to CKWRITE to write past the ex- 
ternally defined boundaries of the file; that is, to write past the 
end-of-file. 

= "30" Lock denied — 

An attempt was made to lock a file already locked by another process; 
or file was not opened with dynamic locking allowed. 

= "31" Unlock denied — 

An attempt was made to unlock a file with CKUNLOCK, but the file 
had not been locked by CKLOCK. 

= "9n" File system error — 

A call to an input/output procedure was unsuccessful as a result of a 
file system error, not one of the error conditions defined for the other 
status values. The value of status-key-2 (n) is a binary number between 
and 255 that corresponds to an MPE file system error code (refer 
to table A-l in appendix A). To convert this binary value to numeric 
display format, call the CKERROR routine (described next in this 
section). 
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STATUS 



USING STATUS 

The value of status can be tested as a whole, or the two characters can be tested separately as 
status-key-1 and status-key-2. In any case, the status of each call should be tested immediately 
following execution of the call. Unless the first character of status = "0", the call was not 
successful. 

For example, a sample status parameter definition might be: 

WORKING-STORAGE SECTION. 



01 STAT. 

02 STATUS-KEY-1 PIC X. 
02 STATUS-KEY-2 PIC X. 



These items can then be referenced in the PROCEDURE DIVISION. For example: to test only 
the first character: 

IF STATUS-KEY-1 NOT = "0" THEN 
GO TO "ERROR-ROUTINE". 

To test the entire status word: 

IF STAT = "23" THEN 

DISPLAY "RECORD NOT FOUND". 

Note that the word STATUS is reserved. 
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KSAM LOGICAL RECORD POINTER 

Many of the KSAM procedures use a logical record pointer to indicate the current record in the 
file. This pointer points to a key value in the key file that identifies the current record in the data 
file. The particular key used, if the file has more than one key, is the key specified in the current 
procedure or the last procedure that referenced a key. 

Procedures that use pointers are either pointer-dependent or pointer-independent. Pointer-depend- 
ent procedures expect the pointer to be positioned at a particular record in order to execute cor- 
rectly. Pointer-independent procedures, on the other hand, execute regardless of where the pointer 
is positioned and, in most cases, they position the pointer. (Refer to table 3-3 for a summary of 
those procedures that either position the pointer or are dependent on the pointer position.) 



Table 3-3. Positioning the Logical Record Pointer 



Procedure 
Name 


Pointer- 
Dependent 


Position of Pointer After 
Execution of Procedure 


CKSTART 


NO 


Points to key whose value was specified in call. 


CKREADBYKEY 


NO 


Points to key whose value was specified in call. 


CKWRITE 


NO 


Points to key whose value is next in key sequence to 
key value in record just written. 


CKREAD 


YES 


Pointer remains positioned to key value for record just 
read; unless next call is to CKREAD, or to CKREWRITE 
followed by CKREAD, in which case, next CKREAD 
moves pointer to next key in key sequence before read- 
ing the record. 


CKDELETE 


YES 


Points to next key value in ascending sequence following 
key value in record just deleted. 


CKREWRITE 


YES 

(sequential 
mode) 


Pointer remains positioned to key value for record just 
modified; unless any key value in record was changed, 
in which case, it points to next key in ascending se- 
quence after the key in the modified record. 


NO 

(random or 
dynamic mode) 
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SHARED ACCESS 

Particular care must be taken when using the logical record pointer during shared access (the file 
was opened with CKOPENSHR). Since the record pointer is maintained in a separate control block 
for each open file, if more than one user opens the same file, one user may modify the key file 
causing the record pointers of other users to point to the wrong key. 

To avoid this problem, you should always lock the file in a shared environment before calling a 
procedure that sets the pointer and leave the file locked until all procedures that depend on the 
pointer have been executed. Thus, if you want to read the file sequentially, delete a record, or 
modify a record, you should lock the file, call a procedure that sets the pointer (such as 
CKSTART), and then call CKREAD, CKDELETE, or CKREWRITE. When the operation is com- 
plete, you can then unlock the file to give other users access to it. 
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SAMPLE KSAM FILE 

The file KSAMFILE illustrated in figure 3-2 is used in all subsequent examples associated with the 
COBOL procedure calls. 



:RUN KSAMUTIL 

>BUILD KSAMFILE;REC=-74,3„ASCII;KEYFILE=KSAMKEY;KEY=B,3,20; & 

KEY=B,23,8„DUP 

character K SAMFILE Data Record word 

1 {reserved for delete code) 



1 - 


»«$^ 


S^«^ 


n — 


*> 


























































23- 
























.11 - 






























































































































73 - 







file creation command 



> NAME (primary key) 



PHONE (alternate key) 



S OTHERDATA 



file description in Working Storage 



WORKING-STORAGE SECTION. 



77 


RECSIZE 


PIC S9(4) 


COMP VALUE 74. 


77 


RESULT 


PIC 9(4) 


VALUE 0. 


01 


REC. 








03 FILLER 


PIC XX 


VALUE SPACES. 




03 NAME 


PIC X(20). 






03 PHONE 


PIC X(8). 






03 OTHERDATA 


PIC X(44). 




01 


DAT. 








03 NAME 


PIC X(20). 






03 PHONE 


PIC X(8). 






03 OTHERDATA 


PIC X(44). 




01 


FILETABLE. 








03 FILENUMBER 


PIC S9(4) 


COMP VALUE 0. 




03 FILENAME 


PIC X(8) 


VALUE "KSAMFILE 




03 I-O-TYPE 


PIC S9(4) 


COMP VALUE 0. 




03 A-MODE 


PIC S9(4) 


COMP VALUE 0. 




03 PREV-OP 


PIC S9(4) 


COMP VALUE 0. 


01 


STAT. 








03 STATUS-KEY-1 


PICX. 






03 STATUS-KEY-2 


PICX. 





Figure 3-2. Representation of KSAMFILE Used in COBOL Examples 
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CKCLOSE 

A call to CKCLOSE terminates file processing for the specified file. 
CALL "CKCLOSE" USING filetable, status 



When processing is completed, a KSAM file should be closed with a call to CKCLOSE. No further 
processing is allowed on the file until a CKOPEN procedure call opens the file. 

CKCLOSE can be executed only for a file that is open. 

PARAMETERS 

filetable an 8-word record containing: the name of the file, its input-output 

type, access mode, the filenumber given the file when it was last 
opened, and a code indicating whether the previous operation on the 
file was successful and if so what it was. (Refer to Filetable Parameter 
discussion earlier in this section.) 

status one- word (two 8-bit characters) set to a pair of values upon comple- 

tion of the call to CKCLOSE. It indicates whether or not the file was 
successfully closed and if not, why not. The left character is set to 
"0" if CKCLOSE is successful, to "9" if not. The right character is 
set to "0" if CKCLOSE is successful, to the file system error code if 
not. (Refer to Status Parameter discussion earlier in this section.) 

USING CKCLOSE 

Upon successful completion of CKCLOSE, the file identified by filetable is no longer available for 
processing. Note that a KSAM file can be closed and then reopened in order to specify a different 
access mode or input-output type. 

EXAMPLES 

Assuming the same filetable and status definitions used to define the sample file in figure 3-2: 

FINISH. 

CALL "CKCLOSE" USING FILETABLE, STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKCLOSE ERROR NO. ", RESULT; 
ELSE DISPLAY "CKCLOSE SUCCESSFUL". 
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CKDELETE 

This procedure logically deletes a record from a KSAM file. 
CALL "CKDELETE" I SING filetuble, status 



In order to logically delete records from a KSAM file, you can use the procedure CKDELETE. A 
logically deleted record is marked by a code of binary l's in the first two characters of the record, 
but is not physically removed from the file. The deletion mark makes such a record inaccessible 
but does not physically reduce the size of the file. The utility program FCOPY (described in 
section II) can be used to compact a KSAM file by copying only active records, excluding deleted 
records, to a new KSAM file. 

CKDELETE deletes the record at which the logical record pointer is currently positioned. There- 
fore, CKDELETE must be preceded by a call that positions the pointer (see table 3-3). 

PARAMETERS 

filetable an 8-word record containing the number and name of the file, its 

input-output type, access mode, and a code indicating whether the 
previous operation was successful and if so what it was. (Refer to 
Filetable Parameter discussion earlier in this section.) 

status one word (two 8-bit characters) set to a pair of values upon comple- 

tion of the call to CKDELETE indicating whether the call was 
successful and if not, why not. (Refer to Status Parameter discus- 
sion earlier in this section.) 

USING CKDELETE 

In order to delete a record, you should first read the record into the working storage section of 
your program with a call to CKREAD if in sequential mode, a call to CKREADBYKEY if in 
random mode, or a call to either if in dynamic mode. CKDELETE can be called only if the file is 
currently open for both input and output (input-output type =2). This allows the record to be 
read into your program's data area and then written back to the file with the delete mark. Follow- 
ing execution of CKDELETE, the deleted record can no longer be accessed. 

SHARED ACCESS. If the file was opened for shared access with CKOPENSHR, you must lock the 
file with CKLOCK before you can delete any records with CKDELETE. Because CKDELETE de- 
pends on the logical record pointer, the call to CKLOCK should precede the call that positions the 
pointer. The call to CKUNLOCK is then called after the call to CKDELETE. To illustrate, the se- 
quence of calls in shared access should be: 



CKLOCK- to lock file 

CKSTART or CKREADBYKEY- to position pointer 



CKDELETE- to delete record at which pointer is positioned 

CKUNLOCK- to unlock file 
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CKDELETE 



Following the call to CKDELETE, the pointer is positioned to the next key following the key in 
the deleted record. 

EXAMPLES 

The following examples show the use of CKDELETE for sequential access using CKREAD and for 
random access using CKREADBYKEY. The WORKING-STORAGE SECTION from figure 3-2 and 
the FINISH procedure from the CKCLOSE example are assumed for these examples. 

1. Sequential Delete. 

In order to delete all records whose primary key begins with "P", first position the file to the start 
of these records with CKSTART and then read each record with CKREAD and delete it with 
CKDELETE. 

WORKING-STORAGE SECTION. 

77 RELOP PICS9(4) COMP. 

77 KEYVAL PIC X(20). 

77 KEYLOC PIC S9(4) COMP. 

77 KEYLENGTH PIC S9(4) COMP. 



PROCEDURE DIVISION. 
START. 

MOVE 2 TO I-O-TYPE. 

MOVE TO A-MODE. 

CALL "CKOPEN" USING FILETABLE, STAT. 

. -, check status 



FIND-REC. 

MOVE TO RELOP.-" test for equality between primary key and KEY 

MOVE "P" TO KEYVAL. 
MOVE 3 TO KEYLOC. 

MOVE 1 TO KEYLENGTH. check first character only 

CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, 

KEYLENGTH. 
IF STATUS-KEY-1 = "0" THEN 

GO TO READ-REC. 
IF STAT = "23" THEN 

DISPLAY "NO RECORD FOUND" 

GO TO FINISH. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKERROR NO. = ", RESULT 

GO TO FINISH. 



3-14 



CKDELETE 



READ-RE C. 

CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. 
IF STATUS-KEY-1 = "1" THEN 

DISPLAY "END OF FILE REACHED" 
GO TO FINISH. 
IF STATUS-KEY-1 = "0" THEN 

IF NAME OF REC NOT LESS THAN "Q " THEN 

DISPLAY "DELETIONS COMPLETED" 
GO TO FINISH; 
ELSE GO TO DELETE-REC; 
ELSE 

DISPLAY "CKREAD ERROR, STATUS = ", STAT 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKERROR NO. ", RESULT. 
GO TO READ-REC. 

DELETE-REC. 

CALL "CKDELETE" USING FILETABLE, STAT. 
IF STATUS-KEY-1 = "0" THEN 
DISPLAY REC, " DELETED" 
GO TO READ-REC; 
ELSE 

DISPLAY "CKDELETE ERROR, STATUS = ", STAT 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKERROR NO. = ", RESULT 
GO TO READ-REC. 

Note: If access is shared, the file must be opened with a call to CKOPENSHR and then locked be- 
fore the call to CKSTART that initially sets the pointer. The file should remain locked while the rec- 
ords to be deleted are read and then marked for deletion. If the file is not locked before CKSTART 
is called, other users can change the file so that the record pointer points to the wrong record. 

2. Random Delete. 

A file containing the primary keys of those records to be deleted from a KSAM file is read into the 
working storage area DAT. These key values are used by CKREADBYKEY to locate and read the 
items to be deleted by CKDELETE. 

PROCEDURE DIVISION. 
START. 

MOVE 2 TO I-O-TYPE, A-MODE. 

CALL "CKOPEN" USING FILETABLE, STAT. 

. check status 

READ-KEY. 

READ DATA-FILE INTO DAT; 

AT END GO TO FINISH. 
CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, NAME OF DAT, RECSIZE. 
IF STATUS-KEY-1 = "0" THEN 

GO TO DELETE-RECORD. 
DISPLAY "CKREADBYKEY ERROR, STATUS = ", STAT. 
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CKDELETE 



IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKERROR NO. = ", RESULT 
GO TO READ-KEY. 
DELETE-RECORD. 

CALL "CKDELETE" USING FILETABLE, STAT. 
IF STATUS-KEY-1 = "0" THEN 

DISPLAY REC, " DELETED" 

GO TO READ-KEY. 
DISPLAY "CKDELETE ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKERROR NO. = ", RESULT. 
GO TO READ-KEY. 



Note: If access is shared, the file must be opened with a call to CKOPENSHR; a call to CKLOCK 
must precede the call to CKREADBYKEY and a call to CKUNLOCK must follow the CKDELETE 
error tests and should precede the return to READ-KEY. 
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CKERROR 

Converts file system error code returned in status to a display format number. 



CALL "CKERROR" USING status, result 



Whenever a "9" is returned as the left character of the status parameter following any call to a 
KSAM procedure, you can call the procedure CKERROR to convert the MPE file system error 
code in the right character of status from a binary number to a display format number. This 
allows you to display the error code. 

PARAMETERS 

status is the status parameter to which a value was returned by a previous 

KSAM procedure call. The entire status parameter, both left and 
right characters, must be specified. 

result is an item to which the error number is returned right justified in 

display format. The item must have a picture of 4 numeric characters 
(PIC 9(4) ). 

USING CKERROR 

The following example shows the WORKING-STORAGE SECTION entries needed to check for 
errors and a call to CKERROR in the PROCEDURE DIVISION that checks for and displays the 
error number if a file system error occurred in a call to process a KSAM file. 

DATA DIVISION. 



WORKING-STORAGE SECTION. 

77 RESULT PIC 9(4) VALUE ZERO. 

01 STAT. 

03 STATUS-KEY-1 PIC X. 

03 STATUS-KEY-2 PIC X. 



PROCEDURE DIVISION. 
START. 



IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT. 
DISPLAY "ERROR NUMBER ", RESULT. 
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CKLOCK 



A call to CKLOCK dynamically locks a KSAM file. 

CALL "CKLOCK" USING filetable, status, lockcond 

When access is shared, you must lock the file before calling CKWRITE, CKREWRITE, or CK- 
DELETE. This insures that another user cannot attempt to modify the file at the same time, and it 
guarantees that the most recent data is available to each user who accesses the file. 

In order to call CKLOCK, the file must have been opened with a call to CKOPENSHR, not 
CKOPEN. 



PARAMETERS 

filetable 



status 



lockcond 



an 8-word record containing the number and name of the file, its input- 
output type, access mode, and a code indicating whether the previous 
operation was successful and if so, what it was. (Refer to Filetable 
Parameter discussion earlier in this section.) 

one-word (two 8-bit characters) set to a pair of values upon completion 
of the call to CKLOCK. It indicates whether or not the file was success- 
fully locked and if not, why not. The status word = "00" if the call was 
successful. It = "30" if the file was locked by another process; it = "9n," 
where n is a file system error code, if the call failed for some other 
reason. (Refer to the Status Parameter discussion earlier in this section.) 

one-word computational item whose value determines the action taken 
if the file is locked by another user when CKLOCK is executed. The 
value is either zero (0) or one (1). 

locking is conditional; if the file is already locked, control is 
returned to your program immediately with the status word set 
to "30." 

1 locking is unconditional; if the file cannot be locked immediately 
because another use has locked it, your program suspends until the 
file can be locked. 



USING CKLOCK 

In order to call CKLOCK, the file must be opened with dynamic access enabled. This can be done 
only with the CKOPENSHR procedure. CKOPEN will not open the file for shared access with 
dynamic locking. 

When users are sharing a file, it is essential to lock the file before modifying it. An error is returned 
if any user attempts to write, rewrite, or delete records without first locking the file. It is also impor- 
tant to avoid situations where one user locks the file and forgets to unlock it. If the file is already 
locked when you call CKLOCK with lockcond set to zero, the call will fail with "30" returned to 
status, and your process will continue. If, however, lockcond is set to 1, your process suspends until 
the other user unlocks the file or logs off. 
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EXAMPLES 



The following example opens file KSAMFILE for shared access with dynamic locking allowed. It 
then locks the file unconditionally. If another user has locked the file, the process suspends until 
the file is unlocked and then continues by locking your file. The status value is checked as soon as 
control returns to your process to insure that the file has been locked before continuing. 

DATA DIVISION. 



77 


LOCKCOND 


PICTURE S9(4) 


COMP 


VALUE 1. 


77 


RESULT 


PICTURE 9(4) 




VALUE 0. 


01 


STATUSKEY. 










02 STATUS-KEY1 


PICTURE X 




VALUE " ". 




02 STATUS-KEY2 


PICTURE X 




VALUE " ". 


01 


FILET ABLE. 










02 FILENUMBER 


PICTURE S9(4) 


COMP 


VALUE 0. 




02 FILENAME 


PICTURE X(8) 




VALUE "KSAMFILE" 




02 I-O-TYPE 


PICTURE S9(4) 


COMP 


VALUE 0. 




02 A-MODE 


PICTURE S9(4) 


COMP 


VALUE 0. 




02 PREV-OP 


PICTURE S9(4) 


COMP 


VALUE 0. 



PROCEDURE DIVISION. 

START. 

CALL "CKOPENSHR" USING FILETABLE, STATUSKEY. 
IF STATUS-KEY1 = "0" THEN GO TO LOCK-FILE. 
IF STATUS-KEY1 = "9" THEN 

CALL "CKERROR" USING STATUSKEY, RESULT 
DISPLAY "ERROR NO. ", RESULT. 

LOCK-FILE. 

CALL "CKLOCK" USING FILETABLE, STATUSKEY, LOCKCOND. 
IF STATUSKEY = "00" 

THEN DISPLAY "CKLOCK IS OK" 
ELSE IF STATUSKEY = "30" 

THEN DISPLAY "FILE LOCKED BY ANOTHER PROCESS" 
ELSE IF STATUS-KEY1 = "9" 

THEN CALL "CKERROR" USING STATUSKEY, RESULT 
DISPLAY "ERROR NO.", RESULT. 
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A call to procedure CKOPEN initiates file processing. 

CALL '-CKOPEN" UNINCJ fikiabk;, $iaiu» 

In order to process a KSAM file, it must be opened with a call to the CKOPEN procedure. CKOPEN 
initiates processing, specifies the type of processing and the access mode; the file must have been 
created previously. You can create a KSAM file through the BUILD command of the KSAMUTIL 
program (refer to section II). 

To open a file means to make it available for processing, to specify the type of processing (input 
only, output only, or both), and to specify the access method (sequential, random, or dynamic). If 
a different type of processing or access method is needed, the file must be closed and opened again 
with the parameters set to new values. 

NOTE 

If you want to open the file for shared access, you must use a 
call to CKOPENSHR, rather than CKOPEN. 

PARAMETERS 

filetable an 8-word record containing the name of the file, its input-output type, 

and access mode. When the open is successful, the first word of this 
table is set to the file number that identifies the opened file. (Refer to 
Filetable Parameter discussion earlier in this section.) 

status one word (two 8-bit characters) set to a pair of values upon completion 

of the call to CKOPEN to indicate whether or not the file was success- 
fully opened and if not why not. Left character is set to "0" if open 
is successful, to "9" if not. Right character is set to "0" if open is 
successful, to file system error code if not. (Refer to Status Parameter 
discussion earlier in this section.) 

USING CKOPEN 

Upon successful execution of CKOPEN, the file named in filetable is available for the type of 
processing specified in filetable. Before the file is successfully opened with CKOPEN, no operation 
can be executed that references the file either explicitly or implicitly. 

The input-output procedures that can be called to process the file depend on the value of the words 
in filetable that specify input-output type and access mode. (Refer to table 3-4 for the procedures 
allowed with the various combinations of input-output type and access mode.) 

A file may be opened for input, output, or input-output, and for sequential, random, or dynamic 
access in the same program by specifying a different call to CKOPEN for each change in input- 
output type or access mode. Following the initial execution of CKOPEN, each subsequent call to 
CKOPEN for the same file must be preceded by a call to CKCLOSE for that file. 

When files are opened for input or input-output, the call to CKOPEN sets the current record pointer 
to the first record in the primary key chain. 
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Table 3-4 Procedures Allowed for Input-Output Type/Access Mode Combinations 



ALLOWED PROCEDURES 


ACCESS MODE 


INPUT-OUTPUT TYPE 


CKREAD 
CKSTART 




(sequential) 


2 

(dynamic) 



(open for input) 


CKREADBYKEY 


1 
(random) 


CKWRITE 




(sequential) 


2 

(dynamic) 


1 
(open for output) 


1 

(random) 


CKREAD 
CKSTART 
CKREWRITE 
CKDELETE 




(sequential) 


2 

(dynamic) 


2 

(open for input/output) 


CKREADBYKEY 
CKWRITE 
CKREWRITE 
CKDELETE 


1 

(random) 



INPUT-OUTPUT TYPE. Word 6 of filetable must be set to one of the following values before 
calling CKOPEN: 

input only 

1 output only 

2 input-output 

Input Only. In general, if you want to allow records to be read or the file to be positioned without 
allowing any new records to be written or any existing records to be changed, you should set the 
input-output type to 0. This input-output type allows you to call CKREAD or CKSTART in 
sequential processing mode, CKREADBYKEY in random mode, or all three in dynamic mode. 

Output Only. If you want to cause all existing records to be deleted when the file is opened and 
then allow new records to be written, you should set the input-output type to 1. This type of open 
deletes all existing records so that records are written to an empty file. When a file is opened for 
output only, you can call CKWRITE in any of the three access modes: sequential, random, or 
dynamic, but you cannot call any other of the KSAM procedures. 

Input-Output. If you want unrestricted file access, you should set the input-output type to 2. 
This access type allows records to be read, positioned, written, rewritten, or deleted. You may call 
CKREAD, CKSTART, CKREWRITE, and CKDELETE (but not CKWRITE) when opened in 
sequential mode; you may call CKREADBYKEY, CKWRITE, CKREWRITE, or CKDELETE (but 
not CKREAD or CKSTART) when opened in random mode. In dynamic mode, any of the KSAM 
procedures may be called. With this type of input-output, existing records are not cleared when 
you write a record with CKWRITE. 
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ACCESS MODE. Word 7 of file table must be set to one of the following values before calling 
CKOPEN: 

sequential access 

1 random access 

2 dynamic access 

Sequential Access. With this type of access, records in the file are read in ascending order based 
on the value of a key within each record. The key is the primary key unless an alternate key was 
specified with CKSTART. Reading starts with the first record in sequence unless a particular 
record was specified with CKSTART. Each time a call to CKREAD is executed, the next record 
in sequence is read from the file. CKREAD and CKSTART are the only procedures that can be 
called in input mode. CKREADBYKEY cannot be specified for any input-output type if the 
access mode is sequential. 

In output mode, CKWRITE is the only procedure that can be called. When access is sequential, 
the record to be written must contain a unique primary key that is greater in value than the key of 
any previously written record. If it is not in sequence, an invalid key sequence error code, "21", 
is returned to status. 

In input-output mode, CKREWRITE and CKDELETE can be specified as well as CKREAD and 
CKSTART, but CKWRITE cannot. 

Random Access. This type of access allows you to read, write, replace, or delete a record with 
any value for its primary key. To read a record, the CKREADBYKEY procedure must be called 
in either input or input-output mode. CKREAD and CKSTART cannot be specified for any 
input-output type when access mode is random. 

When writing a record with CKWRITE in output or input-output mode, the value of the primary 
key in the record need not be greater than the keys of previously written records; that is, records 
can be written in any order. 

In input-output mode, CKREWRITE can be used to replace any record whose primary key matches 
the primary key in the record being written. CKDELETE can be used to delete a record specified 
in a previous CKREADBYKEY call. 

CKWRITE can be used to write a record following existing records in the file if you position to fol- 
low the last sequential record before writing. Use this input-output type if you want to save existing 
data in a file to which you are writing. 

Dynamic Access. Dynamic access allows you to use any call to process a file opened for input- 
output. When the file is opened in dynamic mode, and a call is made to CKREAD or CKSTART, 
the file can be read, but not updated, sequentially. For all other calls, dynamic mode is treated as if 
the file had been opened in random mode. See Random Mode discussion, above. The reason to oepn 
a file in dynamic mode is to allow both sequential and random processing on the same file without 
closing it and then opening it again each time access switches from sequential to random or vice versa. 
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To open a file initially for sequential read: 

WORKING-STORAGE SECTION. 

77 RESULT PIC 9(4) VALUE ZERO. 

01 FILETABLE. 

03 FILENUMBER PIC S9(4) COMP VALUE ZERO. 



03 FILENAME 

03 I-O-TYPE 

03 A-MODE 

03 PREV-OP 
01 STAT. 

03 STATUS-KEY-1 

03 STATUS-KEY-2 



PIC X(8) VALUE "KSAMFILE". 
PIC S9(4) COMP VALUE ZERO. - 
PIC S9(4) COMP VALUE ZERO. 
PIC S9(4) COMP VALUE ZERO. 

PICX. 
PICX. 



input only 
sequential access 



PROCEDURE DIVISION. 
START. 

CALL "CKOPEN" USING FILETABLE , STAT. 
IF STATUS-KEY-1 = "0" THEN GO TO S-READ. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKOPEN FAILED. . .ERROR NO. ' 
STOP RUN. 
S-READ. 



RESULT 



If you subsequently want to write in sequential order to the same file, you should close the file with 
a call to CKCLOSE (described below), move the value 1 (output to I-O-TYPE and then re-open the 
file: 

CALL "CKCLOSE" USING FILETABLE, STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKCLOSE FAILED - ERROR NO. ", 

STOP RUN. 

MOVE 1 TO I-O-TYPE.- output only 

CALL "CKOPEN" USING FILETABLE, STAT. 
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Similarly, to update records in random order in the same file, first close the file, then use the fol- 
lowing MOVE statement to alter the input-output type and access mode in FILETABLE and re- 
open the file: 

CALL "CKCLOSE" USING FILETABLE, STAT. 



MOVE 2 TO I-O-TYPE.-' input-output 

MOVE 1 TO A-MODE. — random access 

CALL "CKOPEN" USING FILETABLE, STAT. 
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A call to CKOPENSHR initiates file processing with dynamic locking and shared access allowed. 
CALL"('KO! J EXSHK"i:SLN(i filetable. status 

In order to process a KSAM file with shared access and dynamic locking, the file must be opened 
with a call to CKOPENSHR. CKOPENSHR is exactly like CKOPEN in that it initiates processing, 
specifies the type of processing, and specifies the access mode. The file must have been created 
previously with the BUILD command of program KSAMUTIL (refer to section II). 

To open a file for shared access means to make it available for processing by more than one user. 
Shared access allows all users to read or position the file, but only one user at a time can modify 
the file by writing new records, or rewriting or deleting existing records. To insure that more than 
one user does not attempt to modify the file at the same time, you must call CKLOCK to dynami- 
Zyloli the mebefore P callin g deprocedures CKWRITE, CKREWRITE, or CKDELETE. After 
modifying the file, you should call CKUNLOCK so that it can be accessed by other users. 

PARAMETERS 

fil eta bl e an 8-word record containing the name of the file, its input-output 

type, and access mode. When the open is successful, the first word of 
this table is set to the file number that identifies the opened file. 
(Refer to Filetable Parameter discussion earlier in this section.) 

status one word (two 8-bit characters) set to a pair of values upon comple- 

tion of the call to CKOPENSHR to indicate whether or not the file 
was successfully opened and if not why not. Left character is set to 
"0" if open is successful, to "9" if not. Right character is set to "0" 
if open is successful, to file system error code if not. (Refer to Status 
Parameter discussion earlier in this section.) 

USING CKOPENSHR 

Except that CKOPENSHR allows shared access and dynamic locking, and CKOPEN does not, a 
call to CKOPENSHR operates exactly like the call to CKOPEN. Upon successful execution of 
CKOPENSHR, the file named in filetable is available for the type of processing specified in file- 
table. Before the file is opened successfully, no operation can be performed that references the file 
either explicitly or implicitly. 

A file may be opened by CKOPENSHR for any of the access modes (sequential, random or dy- 
namic) and for any input-output type (input only, output only, or input-output) allowed with 
CKOPEN. 

Refer to the description of using CKOPEN for the specific affects of opening a KSAM file with the 
various input-output types and access modes. 
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A call to procedure CKREAD makes available the next logical record from a file. 
CALL "CKREAD" USING fiteta&fe ' status, record, recordsize 



In order to read records in sequential order by key value, call procedure CKREAD. The file must 
have been opened in input or input-output mode with access mode specified as either sequential 
or dynamic. 

PARAMETERS 

filetable an 8-word record containing the number and name of the file, its 

input-output type, access mode, and a code indicating whether the 
previous operation was successful and if so, what it was. (Refer to 
Filetable Parameter discussion earlier in this section.) 

status one-word (two 8-bit characters) set to a pair of values upon comple- 

tion of the call to CKREAD to indicate whether or not the record 
was successfully read and if not, why not. (Refer to Status Parameter 
discussion earlier in this section.) 

record a record defined in the WORKING-STORAGE SECTION into which 

the contents of the next sequential KSAM record is read. 

recordsize an integer (S9(4)COMP) containing the length in characters of the 

record being read. It must not exceed maximum record length established 
for the file when it was created. 

USING CKREAD 

The file from which the record is read must be open for sequential or dynamic access (access 
mode = or 2.) It may be opened for input only or input-output (input-output type = or 2), 
but not for output only. 

When the file is opened initially for input or input-output, the logical record pointer is positioned 
at the first sequential record; that is, at the record with the lowest key value. The key used is the 
primary key unless a previous call to CKSTART has specified an alternate key. When a call to 
CKREAD is executed, the record at which the record pointer is currently positioned is read into 
the location specified by record. 

If, when CKREAD is executed, there is no next logical record in the file, the at end condition is 
returned to status; that is, status is set to "10". Note that a call to the procedure CKSTART can 
be used to reposition the pointer for subsequent sequential access according to primary or alternate 
key order. 

In order to update records in sequential order, CKREAD must be called before executing either of 
the update procedures CKREWRITE and CKDELETE. When access is shared, it is important to in- 
clude the call to CKREAD within the same locked portion of code that includes the call to 
CKREWRITE or CKDELETE. This insures that the correct record is modified or deleted. 
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SHARED ACCESS. Because CKREAD is a pointer-dependent procedure (refer to table 3-3), the 
actual record read depends on the current position of the logical record pointer. When access is 
shared, this pointer position can be made incorrect by other users without your program being a- 
ware of it. For this reason, you should lock the file, position the pointer with a pointer-indepen- 
dent procedure, and then call CKREAD. When the last record is read, you should then unlock the 
file so other users can access the file. Example 2 below illustrates how you should read the file se- 
quentially when access is shared. 



EXAMPLE 

Using the WORKING-STORAGE SECTION from figure 3-2 and the FINISH procedure in the 
CKCLOSE example, the following procedures read records in sequential order from file KSAMFILE 
and display them on the standard output device. 



1. Example of Sequential Read 

PROCEDURE DIVISION. 
START. 



MOVE TO I-O-TYPE, A-MODE. 

CALL "CKOPEN" USING FILETABLE, STAT. 

IF STATUS-KEY-1 = "9" 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKOPEN ERROR NO. ", RESULT. 
IF STATUS-KEY-1 NOT = "0" 

DISPLAY "CKOPEN FAILED" 
STOP RUN. 
READ-NEXT. 

CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. 
IF STATUS-KEY-1 = "1" GO TO NEW-POSITION. 
IF STATUS-KEY-1 = "0" 
DISPLAY REC; 
ELSE 

DISPLAY "CKREAD ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "FILE ERROR = ", RESULT. 
GO TO READ-NEXT. 
NEW-POSITION. 



see CKSTAR T example 
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2. Example of Sequential Read with Shared Access 

PROCEDURE DIVISION. 
START. 



MOVE TO I-O-TYPE, A-MODE. 

CALL "CKOPENSHR" USING FILET ABLE, STAT- open file for shared access 



■ test status 



FIND-RECORD. 

MOVE 2 TO RELOP. 
MOVE "000-0000" TO KEYVAL. 
MOVE 23 TO KEYLOC, 
MOVE 8 TO KEYLENGTH. 
MOVE 1 TO LOCKCOND. 

CALL "CKLOCK" USING FILETABLE, STAT, LOCKCOND.- lock file unconditionally 

CALL "CKSTART" USING FILETABLE, 

STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.— position pointer to lowest key value 



, test status 



READ-RECORD. 

CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE- read record 

IF STATUS- KEY-1 = "1"- end of file 

GO TO END-OF-READ. 
IF STATUS-KEY-1 = "0"- if successful, display record read 

DISPLAY REC. 

. test status for errors 



TO TO READ-RECORD. 
END-OF-READ. 

CALL "CKUNLOCK" USING FILETABLE, STAT. - unlock file 
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A call to CKREADBYKEY makes available a record identified by key value from a KSAM file. 



CALL "CKREADBYKEY" USING filelable, status, record, key, keyluc, reconhize. 



Records can be read from a KSAM file in an order determined by key value. This order need not 
be sequential; in fact, it can be any order you specify. This type of access is used to access 
individual records in random order by key value. 



PARAMETERS 



filetable 



status 



an 8-word record containing the number and name of the file, its 
input-output type, access mode, and a code indicating whether the 
previous operation was successful and if so what it was. (Refer to 
Filetable Parameter discussion earlier in this section.) 

one word (two 8-bit characters) set to a pair of values upon completion 
of the call to CKREADBYKEY indicating whether the call was success- 
ful and if not why not. (Refer to Status Parameter discussion earlier in 
this section.) 



record 



key 



keyloc 



a record defined in the WORKING-STORAGE SECTION into which 
the contents of a record located by key value is read. 

an item whose value is used by CKREADBYKEY to locate the record 
to be read. Key values in the file identified by filetable are compared 
to the value of key until the first record with an equal value is found. 

one-word integer (S9(4)COMP) set to the starting character position of 
the key in the KSAM data record (first position is character 1). keyloc 
identifies the file key to be compared with key . 



recordsize 



an integer (S9(4)COMP) containing the length in characters of the record 
being read; it must be less than or equal to the maximum record length 
established for the file at creation. 



USING CKREADBYKEY 

In order to use the CKREADBYKEY procedure, the file must be opened for either input or input- 
output. The access mode can be either random or dynamic, but must not be sequential. 

Execution of CKREADBYKEY causes the value of key to be compared to the value of the key at 
location keyloc in the KSAM file data records. When a key is found whose value is identical to that 
of key, the record pointer is moved to the beginning of that record and the record is read into the 
location record. 

If no record can be found whose key value equals that of key, an invalid key condition is diagnosed 
and status is set to the value "23". Successful execution of CKREADBYKEY is indicated by the 
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value "0" in the left byte of status, unsuccessful execution is indicated by either the invalid key 
return or by a value of "9" in the left byte of status. 

In order to delete records in random or dynamic mode, CKREADBYKEY must be called before 
executing CKDELETE. It is not required prior to CKREWRITE. 

EXAMPLES 

In the following examples, update information is read into the area called DAT in the WORKING- 
STORAGE SECTION. (Note that in this as in the preceding examples, the WORKING-STORAGE 
SECTION from figure 3-2 continues to be useful.) In the first example, the primary keys of records 
in KSAMFILE are searched for values matching the value read into NAME in the DAT record; in 
the second example, an alternate key at location 23 is searched for values matching the value read 
into PHONE in the DAT record. 

1. Read a record located by its primary key value: 

DATA DIVISION. 



WORKING-STORAGE SECTION. 
77 KEYLOC PIC S9(4) COMP. 



PROCEDURE DIVISION. 
START. 



MOVE 2 TO I-O-TYPE, A-MODE.- — prepare to open for input-output, dynamic access 
CALL "CKOPEN" USING FILETABLE, STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKOPEN ERROR NO. ", RESULT. 
IF STATUS-KEY-1 NOT = "0" THEN 

DISPLAY "CKOPEN FAILED" 

STOP RUN. 
FIND-RECORD. 

READ NEW-DATA INTO DAT; - read update records 

AT END GO TO FINISH. 
MOVE 3 TO KEYLOC. 
CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, NAME OF DAT, 

KEYLOC, RECSIZE. 
IF STATUS = "00" THEN 

DISPLAY "RECORD FOUND ", REC 

GO TO FIND-RECORD. 
IF STATUS = "23" THEN 

DISPLAY "RECORD NOT FOUND, KEY = ", NAME OF DAT 

GO TO FIND-RECORD. 
IF STATUS-KEY-1 = "9" THEN 
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CALL "CKERROR" USING STAT, RESULT 
DISPLAY "ERROR NO. ", RESULT 
GO TO FIND-RECORD. 



To find a record by the value of an alternate key, simply change two statements in the preceding 
example so that KEYLOC contains the location of the alternate key and the key value for compari- 
son is found in item PHONE OF DAT rather than in NAME OF DAT: 

FIND RECORD. 

READ NEW-DATA INTO DAT; 

AT END GO TO FINISH. 
MOVE 23 TO KEYLOC. 

CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, PHONE OF DAT 
KEYLOC, RECSIZE. 
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The procedure CKREWRITE replaces a record existing in a KSAM file with another record having a 
matching primary key. 

(' \U. •'CK[IE\VKITI<:'" USING jiinuhL: stains, re^f>*>d, rcconhuc 

You can replace an existing record in a KSAM file with the procedure CKREWRITE. This proce- 
dure replaces a record previously read from the file with another record whose primary key matches 
the primary key of the record being replaced. 

PARAMETERS 

filetable an 8-word record containing the number and name of the file, its input- 

output type, access mode, and a code indicating whether the previous 
operation was unsuccessful and if so what it was. (Refer to Filetable 
parameter discussion earlier in this section.) 

status one word (two 8-bit characters) set to a pair of values upon the comple- 

tion of the call to CKREWRITE indicating whether or not the call was 
successful and if not why not. (Refer to Status Parameter discussion 
earlier in this section.) 

record a record defined in the WORKING-STORAGE SECTION containing 

data to be written as a logical record to the file replacing the record 
with a matching primary key. 

recordsize an integer (S9(4)COMP) containing the length in characters of the record 

to be written. It must not exceed the maximum record length established 
for the file creation. 

USING CKREWRITE 

In order to call procedure CKREWRITE, the file must be open for both input and output (input- 
output type=2). The access mode can be sequential, random, or dynamic. If access mode is sequential, 
CKREAD must have been executed successfully just prior to the call to CKREWRITE. In random or 
dynamic mode, no prior read is required; the system searches the file for the record to be rewritten. 

REWRITE IN SEQUENTIAL MODE. When the file is opened in sequential mode (access mode = 0), 
CKREAD must be executed before CKREWRITE. The primary key in the record to be written by 
CKREWRITE must be identical to the primary key in the record read by CKREAD. A simple way 
to insure that the keys match is to read a record into WORKING-STORAGE, modify it without 
altering the primary key, and then write it back to the file using CKREWRITE. Since the primary 
key is not changed, the sequence of records in the file is not affected. 

Rewriting Records With Duplicate Keys. If you want to rewrite in sequential mode all the records in 
a chain of records with duplicate keys, use either CKSTART or CKREADBYKEY to position to the 
first record in the chain. Then call CKREWRITE to update the first record in the chain. Subsequent 
calls depend on whether you are changing any key value in the record (not necessarily the selected 
key). 
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If no key in the record is changed, the record pointer continues to point to the current record. 
Only a subsequent CKREAD advances the pointer to the next record in the duplicate key chain. 
In this case, you can issue CKREAD and CKREWRITE calls until all records with the duplicated 
key value have been rewritten. 

If any key in the record is changed, the new key is written to the end of the chain of duplicate keys 
in the key file. After the first call to CKREWRITE, the record pointer points to the record whose 
key value follows the changed key. Since this key is now at the end of the chain of duplicate keys, 
a subsequent call to CKREWRITE skips all records with keys in the duplicate key chain and re- 
writes the record with the next higher key value. In this case, you must precede each call to CKRE- 
WRITE with a call to CKSTART or CKREADBYKEY in order to update all subsequent records with 
duplicate keys. 

If you are updating a primary key value which is duplicated, it is good practice to use CKDELETE 
to delete the selected record and then rewrite it as a new record with CKWRITE. 

REWRITE IN RANDOM MODE. When the file is opened in random or dynamic mode (access 
mode = 1 or 2), no prior call to a read procedure is needed. You specify the record to be written 
in WORKING-STORAGE and then call CKREWRITE. However, you must use the primary key 
to position to the record to be modified. When the procedure is executed, the file is searched for a 
record whose primary key matches that of the record to be written. If such a record is found, it is 
replaced by the record specified in CKREWRITE. If not found, an invalid key condition is diagnosed 
and status is set to the value "23". 

A call to CKREWRITE in random mode only updates the first record with a key in the chain of 
duplicate keys. 

POSITION OF POINTER. Regardless of the mode, after any call to CKREWRITE that does not 
modify a key value, the record pointer is positioned to the key of the record just modified. How- 
ever, if any key in the modified record was changed, the record must be deleted and then rewritten 
by a write procedure. If the access mode is sequential and a key was modified, the pointer is moved 
to the record with the next key value in ascending sequence after the modified key. If the access 
mode is random or dynamic, and a key was modified, the pointer is moved to the record with the 
next key in ascending sequence after the primary key in the modified record. This means that in 
random or dynamic mode the key pointer may change if it was pointing to an alternate key before 
the call to CKREWRITE. 

REWRITE WITH SHARED ACCESS. If the file was opened for shared access with CKOPENSHR, 
then you must lock the file with a call to CKLOCK before rewriting any records with CKRE- 
WRITE. After the records are rewritten, you should unlock the file with CKUNLOCK. 

To insure that you are updating the correct record in sequential mode, you should call CKLOCK 
before positioning the pointer with CKSTART or CKREADBYKEY, then specify the sequential 
calls to CKREAD and CKREWRITE before unlocking the file with CKUNLOCK. This insures 
that no other users change the position of the pointer while you are sequentially updating the file. 

INVALID KEY. In sequential mode, the invalid key condition exists when the record just read by 
CKREAD and the record to be written by CKREWRITE do not have the same primary key value. 
In random or dynamic mode, an invalid key condition exists if no record can be found in the file 
whose primary key matches that of the record to be written by CKREWRITE. In either case, status 
is set to the value "23". 

Regardless of mode, an invalid key condition occurs if an alternate key value in the record to be 
written duplicates a corresponding alternate key for which duplicates are prohibited. When rewrit- 
ing a record, try to avoid specifying an alternate key value that may duplicate a value existing in 
the file unless duplicates are allowed for the key. A duplicate key condition where duplicates are 
not allowed causes status to be set to "22" and the procedure is not executed. 
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EXAMPLES 

The first example is of a sequential update that clears the value of an item in each record of the 
file. The second example searches the file for a record whose primary key has a particular value in 
order to change the alternate key for that record. Both examples assume the WORKING-STORAGE 
SECTION from figure 3-2 and the FINISH procedure from CKCLOSE. 
1. Sequential Update. 

Use CKSTART to position the current record pointer to the start of the file. Then read each record 
in sequence and set its non-key items to blanks: 

DATA DIVISION. 



WORKING-STORAGE SECTION. 

77 RELOP PICS9(4) COMP. 

77 KEYVAL PIC X(20). 

77 KEYLOC PIC S9(4) COMP. 

77 KEYLENGTH PIC S9(4) COMP. 



items required by CKSTART 



PROCEDURE DIVISION. 
START. 

MOVE 2 TO I-O-TYPE. 

MOVE TO A-MODE. 

CALL "CKOPEN" USING FILETABLE, STAT. 



check status 



set up CKSTART parameters to start 
reading at lowest alternate key value 



UPDATE-FILE. 

MOVE 1 TO RELOP. 

MOVE "000-0000" TO KEYVAL.-, 

MOVE 23 TO KEYLOC. 

MOVE 8 TO KEYLENGTH. 

CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH. 

IF STATUS-KEY-1 = "0" THEN 

GO TO READ-RECORD; 
ELSE 

DISPLAY "CKSTART ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKERROR NO. ", RESULT 
GO TO FINISH. 
READ-RECORD. 

CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. 
IF STATUS-KEY-1 = "1" THEN 

GO TO FINISH. end of file 

IF STATUS-KEY-1 = "0" THEN 

GO TO WRITE-RECORD 
ELSE 

DISPLAY "CKREAD ERROR.STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKERROR NO. ", RESULT 
GO TO READ-RECORD. 
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WRITE-RECORD. 

MOVE SPACES TO OTHERDATA OF REC. 
CALL "CKREWRITE" USING FILETABLE, 
IF STATUS-KEY-1 = "0" THEN 

DISPLAY NAME OF REC, "DATA CLEARED" 

GO TO READ-RECORD. 
DISPLAY "CKREWRITE ERROR, STATUS = ", 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT, 

DISPLAY "CKERROR NO. = ", 

GO TO READ-RECORD. 

Note: If the file was opened for shared access with a call to CKOPENSHR, then the file should be 
locked with a call to CKLOCK before the call to CKSTART. The file should be unlocked with a 
call to CKUNLOCK only when the final record is updated, probably in the FINISH procedure. 



2. Random Update. 

Find the record with the primary key "ECKSTEIN, LEO " and change the value of the secondary 
key to "257-5137": 

PROCEDURE DIVISION. 
START. 



MOVE 2 TO I-O-TYPE, A-MODE. 

CALL "CKOPEN" USING FILETABLE, STAT. 

IF STATUS-KEY-1 = "0" THEN 

GO TO F-UPDATE. 
DISPLAY "CKOPEN ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKERROR NO. = ", RESULT 
GO TO FINISH. 
F-UPDATE. 

MOVE "ECKSTEIN, LEO " TO NAME OF REC. 

MOVE "257-5137" TO PHONE OF REC. 

MOVE SPACES TO OTHERDATA OF REC. 

CALL "CKREWRITE" USING FILETABLE, STAT, REC, RECSIZE. 

IF STATUS-KEY-1 = "0" THEN 

DISPLAY REC, "UPDATED" 

GO TO FINISH. 
IF STAT = "23" THEN 

DISPLAY NAME OF REC, " NOT FOUND" 

GO TO FINISH. 
DISPLAY "CKREWRITE ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKERROR NO. = ", RESULT. 
GO TO FINISH. 
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A call to procedure CKSTART allows you to position the record pointer to a particular record de- 
fined by its primary or alternate key value. 

CALL "CKSTART" USING file table, status, relop\ kep keyloc, key length 

In order to position the current record pointer to a location in the file defined by a key value, call 
CKSTART. Since CKSTART is used in preparation for sequential retrieval of records with 
CKREAD, the file must be open for sequential or dynamic access, not random, and for input or 
input-output, not output only. 



PARAMETERS 

filetable 



status 



relop 



an 8- word record containing the number and name of the file, its 
input-output type, access mode, and a code indicating whether the 
previous operation was successful and if so, what it was. (Refer to 
Filetable Parameter discussion earlier in this section.) 

one word (two 8-bit characters) set to a pair of values upon completion 
of the call to CKSTART to indicate whether or not the call was success- 
ful and if not why not. (Refer to Status Parameter discussion earlier in 
this section.) 

one-word integer (S9(4)COMP) code that specifies a relation between 
the key value specified in the call to CKSTART and the key value in 
the record to which the record pointer is to be positioned: 



™ record key is equal to key 
-13 — record key is greater than key 
2 )- record key is greater than or equal to key 



key 



keyloc 



keylength 



an item whose value is used by CKSTART to locate the record at 
which to position the record pointer. The values of a specified file 
key are compared in ascending order to the value of key according to 
the relation specified by relop. 

one-word integer (S9(4)COMP) set to the starting character location 
of a key in the KSAM file data record (first position is character 1). 
The key at keyloc is compared to key. 

one-word integer (S9(4)COMP) set to the length of key; the length 
must be less than or equal to the length of the key defined by keyloc. 
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USING CKSTART 



When CKSTART is executed, the key file is searched for the first key in the set of keys at location 
keyloc whose value when compared with key satisfies the comparison specified by relop. The 
current record pointer is positioned to the beginning of the record in the data file associated with 
the key found by CKSTART. 

The specified length of key (key length) may be less than the length of the key in the file; if so, the 
comparison proceeds as if the file key were truncated on the right to the same length as key length. 

If no record can be found whose key value satisfies the comparison, an invalid key condition is 
returned to status; that is, status is set to "23". 

SHARED ACCESS. If you use CKSTART to position the pointer before reading or updating the 
file sequentially in a shared environment, you must lock the file with a call to CKLOCK before 
calling CKSTART. Then, after you have completed the sequential operations, you can unlock the 
file with a call to CKUNLOCK. If you wait to lock the file until after the call to CKSTART, anoth- 
er user can change the structure of the key file so that the position of the pointer becomes invalid 
for any subsequent call to a procedure that depends on the pointer position. (Refer to table 3-3 
for a list of the pointer-dependent procedures.) 



EXAMPLES 

Four new items must be added to the WORKING-STORAGE SECTION in figure 3-2; otherwise, 
the same WORKINGSTORAGE SECTION is used. The new items are: 

77 RELOP PICS9(4) COMP. 

77 KEYVAL PIC X(20). 

77 KEYLOC PIC S9(4) COMP. 

77 KEYLENGTH PIC S9(4) COMP. 

Each of these items is assigned the value appropriate to the operation to be performed by statements 
in the PROCEDURE DIVISION. Note that the length of array KEYVAL can be made shorter by 
assigning a value less than 20 to KEYLENGTH but it cannot be made longer than 20 characters. 
Since there is no key in KSAMFILE longer than 20 characters, this allows comparison to be made 
on the longest key. 

The following example shows the statements needed to display the records in KSAMFILE in order 
by the alternate key PHONE that starts in location 23 and has a length of 8 characters. It assumes 
the file is open for input or input-output and that access mode is sequential. It also assumes the 
FINISH procedure from the CKCLOSE example. 
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1. Position by alternate key sequence: 

NEW-POSITION. 

MOVE 2 TO RELOP. - find key value greater than or equal to KEYVAL 

MOVE "000-0000" TO KEYVAL. 

MOVE 23 TO KEYLOC. 

MOVE 8 TO KEYLENGTH. 

CALL "CKSTART" USING FILET ABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH. 

IF STATUS = "23" THEN GO TO FINISH.- no record found 

IF STATUS-KEY-1 = "0" THEN GO TO READ-BY-PHONE.- lowest key value found 

DISPLAY "CKSTART ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "ERROR NUMBER = ", RESULT. 
GO TO FINISH. 

READ-BY-PHONE. 

CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. 

IF STATUS-KEY-1 = "1" THEN GO TO FINISH.- end-of-file 

IF STATUS-KEY-1 = "0" THEN 
DISPLAY REC; 

ELSE DISPLAY "CKREAD ERROR,STATUS = ", STAT 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "ERROR NUMBER = ", RESULT. 
GO TO READ-BY-PHONE. 



In the next example, CKSTART is used to position to the beginning of the series of names beginning 
with the letter "T". The KSAM file key is located at character position 3 (NAME key); the param- 
eter KEYVAL is set to the value "T"; the key length for purposes of comparison is set to 1; and 
RELOP is set to 0. Thus the record pointer is positioned at the first key found whose value (when 
the key is truncated to 1 character) is equal to "T". Note that this example reads not only all 
names beginning with "T", but also reads all names that begin with letters following "T". To 
read only the names beginning with "T", the program must add a test for the end of the "T" 
names. 
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2. Using a Generic Key 

POSITION. 

MOVE TO RELOP. -* find key equal to KEY value 

MOVE "T" TO KEYVAL. 

MOVE 3 TO KEYLOC. 

MOVE 1 TO KEYLENGTH. 

CALL "CKSTART" USING FILET ABLE, ST AT, RELOP, KEYVAL, KEYLOC, KEYLENGTH. 

IF STATUS = "23" THEN GO TO FINISH. 

IF STATUS-KEY-1 = "0" THEN 

GO TO READ-NAMES. 
DISPLAY "CKSTART ERROR, STATUS = ", STAT. 
IF STATUS-KEY-1 - "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "ERROR NUMBER = ", RESULT. 
GO TO FINISH. 
READ-NAMES. 

CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. 
IF STATUS-KEY-1 = "1" THEN GO TO FINISH. 
IF STATUS-KEY-1 = "0" THEN 

DISPLAY REC; 
ELSE 

DISPLAY "CKREAD ERROR, STATUS = ", STAT. 

IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "ERROR NUMBER = ", RESULT. 
GO TO READ-NAMES. 
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A call to CKUNLOCK unlocks a KSAM file dynamically locked by CKLOCK. 

CALL "CKUNLOCK" USING filetable, status 

A file locked by CKLOCK is released for use by other users with a call to CKUNLOCK. (If you log 
off from any connection with the system, the file is also unlocked.) Since dynamic locking takes 
place during shared access to the same file by more than one user, it is important that any file 
locked by CKLOCK be unlocked as soon as possible by CKUNLOCK. 

To use CKUNLOCK, the file must be opened for shared access with dynamic locking allowed. This 
can only be done by calling CKOPENSHR to open the file, not CKOPEN. 

PARAMETERS 

filetable an 8-word record containing the number and name of the file, its input- 

output type, access mode, and a code indicating whether the previous 
operation was successful and if so, what it was. (Refer to Filetable 
Parameter discussion earlier in this section.) 

status one-word (two 8-bit characters) set to a pair of values upon completion 

of the call to CKUNLOCK. It indicates whether or not the file was suc- 
cessfully unlocked and if not, why not. The status word is set to "00" 
if the file was unlocked successfully; to "31" if the file was not locked; 
or to "9rc" where n is a binary file system error code if the call fails for 
any other reason. (Refer to Status Parameter discussion earlier in this 
section.) 

USING CKUNLOCK 

After calling CKUNLOCK, you should always check the status parameter to make sure that the pro- 
cedure was executed successfully. When successful, the file locked by CKLOCK is again made avail- 
able for access by other users. If the file was not locked by CKLOCK, when CKUNLOCK is called, 
status is set to "31." 

EXAMPLES 

The following example unlocks a file previously locked by CKLOCK. (Refer to the CKLOCK 
example.) 
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VALUE " ". 
VALUE " ". 



77 RESULT PICTURE 9(4) VALUE 0. 

01 STATUSKEY. 

02 STATUS-KEY1 PICTURE X 

02 STATUS-KEY2 PICTURE X 
01 FILETABLE. 

02 FILENUMBER PICTURE S9(4) COMP VALUE 0. 

02 FILENAME PICTURE X(8) VALUE "KSAMFILE" 

02 I-O-TYPE PICTURE S9(4) COMP VALUE 0. 

02 A-MODE PICTURE S9(4) COMP VALUE 0. 

02 PREV-OP PICTURE S9(4) COMP VALUE 0. 



PROCEDURE DIVISION. 



CALL "CKUNLOCK" USING FILETABLE, STATUSKEY. 
IF STATUSKEY = "00" 

THEN DISPLAY "CKUNLOCK IS OK" 
ELSE IF STATUSKEY = "31" 

THEN DISPLAY "FILE NOT PREVIOUSLY LOCKED BY THIS PROCESS" 
ELSE IF STATUS-KEY1 = "9" 

THEN CALL "CKERROR" USING STATUSKEY, RESULT 
DISPLAY "ERROR NO.", RESULT. 
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Procedure CKWRITE copies a logical record from the program's data area to an output or an 
input-output file. 



CALL "CKWRITE" USING fUetable, status, record, recordsize 



A call to procedure CKWRITE may be used to write records to a KSAM file either in sequential 
order or randomly by key value. The file must have been opened for output or for input-output, 
but not for input only. 



PARAMETERS 



file table 



status 



record 



recordsize 



an 8-word record containing the number and name of the file, its 
input-output type, access mode, and a code indicating whether the 
previous operation on the file was successful and if so what it was. 
(Refer to Filetable Parameter discussion earlier in this section.) 

one-word (two 8-bit characters) set to a pair of values upon completion 
of the call to CKWRITE to indicate whether or not the record was 
successfully written and if not why not. (Refer to Status Parameter 
discussion earlier in this section.) 

a record defined in the WORKING-STORAGE SECTION containing 
data to be written to the file by CKWRITE. 

an interger (S9(4)COMP) containing the length in characters of the 
record to be written. It must not exceed the maximum record length 
established for the file when it was created, and it must be long enough 
to contain all the keys. 



USING CKWRITE 



The file to which the content of record is written must be open for output only if sequential mode 
is specified. It may be opened for output or input-output if the access mode at open is random or 
dynamic. 

WRITING IN SEQUENTIAL MODE. When the file is opened for sequential access (access 
mode = 0) and for output only (I-O type = 1), then records must be written to the file in ascending 
sequential order by primary key value. The value of the primary key in the record to be written 
must be greater than the value of the primary key in any record previously written to the file. 
This insures that the records written to the file are initially in ascending order physically as well as 
logically. 
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When I-O type = 1, CKWRITE writes records starting at the beginning of the file, thereby effectively 
clearing any records previously written to the file. 

WRITING IN RANDOM MODE. In a file opened for random or dynamic access (access mode = 1 
or 2) and for output only or for input-output (I-O type = 1 or 2), records can be written in any 
order; the value of the primary key need not be in any particular relation to the primary key values 
of previously written records. 



If you want to preserve existing records in the file, you should open the file with the input-output 
type equal to 2; when input-output type = 1, all existing records are cleared prior to the write. 

WRITING WHEN ACCESS IS SHARED. If the file was opened for shared access with 
CKOPENSHR, then you must lock the file with a call to CKLOCK before writing any records. 
After the records are written, you should unlock the file with a call to CKUNLOCK. 

INVALID KEY. The invalid key condition (left byte of status = "2") can occur as a result of the 
following circumstances: 

• File was opened for sequential access in output mode and the value of the primary key in the 
record being written is less than or equal to the value of the primary key in the record just 
written; status = "21". 



• 



File was opened for sequential or random access in output or input-output mode and the value 
of the primary key is equal to the value of the primary key in an existing record; status = "22". 



• File was opened for sequential or random access in output or input-output mode and the value 
of an alternate key for which duplicates are prohibited equals the value of a corresponding key 
in an existing record; status = "22". 

• File was opened for sequential or random access in output or input-output mode and an 
attempt was made to write a record beyond the physical bounds of the file; status = "24". 

EXAMPLES 

Assume a KSAM file called KSAMFILE with records containing 74 characters (72 characters of 
data following two characters reserved for the delete code), one primary key containing a name, 
and an alternate key containing a phone number. The data is read from an input file called 
DATA-FILE. (Refer to figure 3-2 for a diagram of the structure of this file.) 

The first example writes data to KSAMFILE in sequential order by the primary key. The second 
example, using the same DATA DIVISION and the same FINISH procedure, writes one record to 
the file containing the value "ADAMSON JOHN" as its primary key value. 
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1. Example of Sequential Write. 
DATA DIVISION 

WORKING-STORAGE SECTION. 



77 


RECSIZE 


PIC S9(4) 


COMP VALUE 74. 


77 


RESULT 


PIC 9(4) 


VALUE 0. 


01 


REC. 








03 FILLER 


PIC XX 


VALUE SPACES. 




03 NAME 


PIC X(20). 






03 PHONE 


PIC X(8). 






03 OTHERDATA 


PIC X(44). 




01 


DAT. 








03 NAME 


PIC X(20). 






03 PHONE 


PIC X(8). 






03 OTHERDATA 


PIC X(44). 




01 


FILETABLE. 








03 F1LENUMBER 


PIC S9(4) 


COMP VALUE 0. 




03 FILENAME 


PIC X(8) 


VALUE "KSAMFILE 




03 I-O-TYPE 


PIC S9(4) 


COMP VALUE 0. 




03 A-MODE 


PIC S9(4) 


COMP VALUE 0. 




03 PREV-OP 


PIC S9(4) 


COMP VALUE 0. 


01 


STAT. 








03 STATUS-KEY-1 


PICX. 






03 STATUS-KEY-2 


PICX. 





PROCEDURE DIVISION. 
START. 



MOVE 1 TO I-O-TYPE. - 

CALL "CKOPEN" USING FILETABLE, STAT. 
IF STATUS-KEY-1 = "0" THEN GO TO WRITE-F. 

STAT. 



set type to output only 



DISPLAY "CKOPEN ERROR, STATUS = 
IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 

DISPLAY "CKERROR NO. ", RESULT. 
STOP RUN. 
WRITE-F. 

READ DATA-FILE INTO DAT; 

AT END GO TO FINISH. 
MOVE CORRESPONDING DAT TO REC. 

CALL "CKWRITE" USING FILETABLE, STAT, REC, RECSIZE. 
IF STATUS-KEY-1 = "0" THEN 

DISPLAY REC. 

GO TO WRITE-F. 
IF STAT = "21" THEN 

DISPLAY "SEQUENCE ERROR IN ", NAME OF REC 

GO TO WRITE-F. 



3-44 



CKWRITE 



IF STAT = "22" THEN 

DISPLAY "DUPLICATE KEY ", NAME OF REC 

GO TO WRITE-F. 
IF STAT = "24" THEN 

DISPLAY "END OF FILE" 

GO TO FINISH. 



FINISH 

CLOSE DATA-FILE. 

CALL "CKCLOSE" USING FILETABLE, STAT. 

IF STATUS-KEY-1 = "9" THEN 

CALL "CKERROR" USING STAT, RESULT 
DISPLAY "CKCLOSE ERROR NO. ", RESULT. 

STOP RUN. 



2. Example of random write. 

PROCEDURE DIVISION. 
START. 



MOVE 1 TO I-O TYPE.- output only 

MOVE 2 TO A-MODE. random access 

CALL "CKOPEN" USING FILETABLE, STAT. 

check status 

FIND-REC. 

READ DATA-FILE INTO DAT; 

AT END GO TO FINISH. 
IF NAME OF DAT = "ADAMSON JOHN" THEN 

GO TO WRITE-REC; 

ELSE GO TO FIND-REC. 
WRITE-REC. 

MOVE CORRESPONDING DAT TO REC. 

CALL "CKWRITE" USING FILETABLE, STAT, REC, RECSIZE. 

IF STATUS-KEY-1 = "0" THEN 

DISPLAY REC," RECORD WRITTEN" 

GO TO FINISH. 
IF STAT = "22" THEN 

DISPLAY "DUPLICATE KEY" 

GO TO FINISH. 
IF STAT = "24" THEN 

DISPLAY "NO ROOM IN FILE" 

GO TO FINISH. 
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EXAMPES OF KSAM FILE ACCESS 
FROM COBOL PROGRAM 



The following three examples illustrate KSAM file access from a COBOL program. The file 
accessed in each example is called KSAMFILE. It was created previously by the KSAMUTIL 
>BUILD command with BYTE type keys: the primary key containing the name of a person and 
the alternate key containing his telephone number; the remaining data in each record is his 
address. 

EXAMP1. SEQUENTIAL WRITE 

The first example reads data from an input file into working storage and then writes it to a KSAM 
file. Access mode is sequential so that as each record is written, the keys are linked in sequential 
order although the records are not physically written in sequence. Input-output type is output 
only, the only type allowed for the procedure CKWRITE. The following procedures are illustrated: 

CKOPEN 

CKWRITE 

CKCLOSE 



Input to EXAMP1: 












NOLAN 




JACK 


9?T..<t975 


S>67 WEEO AVE, 


SUNNYVALE. 


C*. 


9<»087 


HU^ODA 




JOE 


227_p21* 


1100 SAINT PETER r.T, 


LOS ALTOS 


C*. 


9*022 


ECKSTEIN 


LEO 


?87_5137 


5303 STEVENS CREEk 


SANTA CLARA 


CA. 


95050 


C«WUIN 




HICK 


H7P-7C18 


11100 WOLFE ROAD 


CUPERTINO 


CA. 


9*053 


PASbY 




LINDA 


?9?>-1 18/ 


TOWN ft, CNTRY VILLAGE 


S«N JOSE 


CA. 


9*102 


$ttLY 




HENkY 


?9"3«.*220 


llitt* LEBERTY st, 


EL CtRRlTO 


CA. 


9*053 


QUbERT 




GfcR*Y 


2SP_553S 


123*5 TELEGRAPH AyE. 


BERKELEY 


CA. 


90871 


TU^NEWR 


IVAN 


<J8*-8*9fl 


32905 EMERSOn ST, 


OAKLAND 


CA, 


98?34 


v'mITe 




GOKUON 


39P-OJOI 


<»350 ASH3Y AVE. 


BERKELEY 


CA. 


9123* 


WtSTtH 




EUuta 


2tt7_<,i>9B 


1256 KInSFISHp;p ST. 


SUNNYVALE 


CA. 


*3098 


oBtND 


OF 


TNHUT FOR 


t X AWP1** 










Program 


EXAMP1: 












OOlOOQ 


Identification division 


• 








001100 


PROGRAM. IDt 


EXAMP1, 










001200 


ENVIRONMENT DIVISION, 










001300 


INPUT-OUTPUT 


SECTION, 










001*00 


FILE-CONTROL, 












Q01500 




SELECT SEQ-DATA ASSIGN TO msEQDATA", 








001600 


DATA DIVISION. 










001700 


FILE SECTION, 












001800 


FD 


SEQ-DATA 












0O1900 




LABEL RECORDS ARE STANDARD, 








002000 


01 


INPUT-REC. 










002100 




05 REAL-DATA PIC 


X(72) . 








002200 


WORKINQ-STORAOE SECTION 


t 








Q02300 


77 


RECSIZE 


PIC S9(ft) 


C0MP VALUE 74. 








002*00 


77 


RESULT 


PIC 9(4) 


v*lue zero. 








002500 


01 


DATA-REC 


1 










002600 




05 FILLER PIC XX VALUE SPACES. 








0O2700 




05 REAl« 


•DATA PIC X<72> . 









Figure 3-3. Sequential Write Using COBOL 



3-46 



Q02800 


01 


FILETASLE. 






002900 




02 filenumbfr pic s9<4> comp value 0. 






003000 




02 FILENAME PIC X<8) VALUE "GKSAMFlL". 






003100 




02 I-0- T YPE PIC S9(*J COMP VALUE 1. 






003200 




02 A-MqDE PIC S9(4) COMP VALUE 0. 






003300 




02 PREV-OP PIC S9(4) COMP VALUE 0. 






003*00 


01 


STATUSKEY. 






003500 




02 STATUS-KfY-l PIC X. 






003600 




02 STATUS-KEY-2 PIC X, 






003700 










003800 


PROCEDURE DIVISION. 






003900 


START, 






00*000 




OPEN INPUT SEQ-DATA. 






00*100 




CALL "CKOPEN" USING FILETABLE, STATUSKEY. 






00*200 




IF STATUS-KEY-! s "9" THEN 






Q0*300 




CALL "CKERROR" USING STATUSKEY, RESULT 






00**00 




DISPLAY "CKOPEN ERROR NO. ". RESULT. 






00*500 




IF STATUS-KEY-! NOT > "0" THEN 






00*600 




DISPLAY "CKOPEN FAILED" 






00*700 




STOP RUN, 






00*800 


Loop. 






00*900 




KEAD SEQ-OATA 






005000 




At END GO TO FINISH, 






005100 




MOVE CORR INPUT-REC TO DATA-REC. 






005200 




CAUL "CKWRITE" USINQ FILETABLE, STATUSKEY. DATA-REC* 




005300 




RECSIZE. 






005*00 




IF STATUSKEY a "02" THEN 






005500 




DISPLAY "DUPLICATE KEY»t 






005600 




IF STAjUS-KEY-1 « "0" THEN 






005700 




DISPLAY DATA-REC 






005800 




GO TO LOOP, 






005900 




IF STATUS-KEY-! * "9" THEN 






006000 




CALL "CKERROR" USING STATUSKEY, RESULT 






006100 




DISPLAY "CKWRITE ERROR NO, ", RESULT 






006200 




OISPLAY DATA-REC 






006300 




GO TO LOOP, 






006<>00 


FIMISH. 






006500 




CLOSE SEQ-DATA, 






006600 




CALL "CKCLOSE" USING FILETABLE, STATUSKEY, 






006700 




IF STATUS-KEY-1 s "9" THEN 






006800 




Call "Ckerror" using statuskey. result 






006900 




DISPLAY "CKCLOSE ERROR NO, ", RESULT, 






007000 




STOP RUN, 






Output from EXAMP1 Execution: 






NOLAN 




JACK 923-4975 9ft7 REED AVE, SUNNYVALE 


CA. 


9*oB7 


HOSODA 




JOE 227-881* U80 SAINT PETER CT. LOS ALTOS 


CA, 


9*088 


ECKSTEIN 


LEO 287-5137 5303 STEVENS CREEK SANTA CLARA 


CA, 


95050 


caaDlN 




RICK 578-7018 H100 WOLFE ROAD CUPERTINO 


CA. 


9*053 


PASBY 




LINDA 295-1187 TOWN & CNTRY VILLAGE SAN JOSE 


CA, 


9*102 


SEELY 




HENRY 293-*22o H** LEBE«TY ST, el CERRITO 


CA, 


9*053 


R09ERT 




GERRY 259-5535 183*5 TELEGRAPH AVE* BERKELEY 


CA. 


90871 


TU^NEWR 


IVAN 98*-8*98 ??905 EMERSON ST, OAKLAND 


CA. 


98234 


WHITE 




GORDON 398-0301 *350 ASHBY AVE. BERKELEY 


CA, 


91234 


WESTER 




ELDER 287-459$ 1356 KINGFISHER ST, SUNNYVALE 


CA, 


*3098 


END OF 


PROGRAM 
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EXAMP2. SEQUENTIAL READ 

The second example reads the file KSAMFILE in sequential order by primary key (NAME) and 
prints each record as it is read. It then repositions the file to the first sequential record according 
to the alternate key (PHONE) and prints each of the records as it is read in this order. The file is 
opened in sequential mode for input only. .The following procedures are illustrated: 

CKOPEN 
CKREAD 
CKSTART 
CKCLOSE 



Program EXAM2: 

ooiooo identification division, 

001100 PROGRAM-IOt EXAMP2, 

001200 ENVIRONMENT DIVISION, 

001300 INPUT-OUTPUT SECTION, 

O01400 FlLE-CONTROt,. 

(101500 SELECT S E Q.DaTA ASSIGN TO "SEQDATA" . 

001600 DATA DIVISION, 

C01700 WORKINli.STORAGE SECTION. 

rtOlSoO 77 RECSIZE PIC S9<4) COMP VALUE 74. 

001900 77 RESULT PIC 9(4) vA|_UE ZERO. 

002000 77 KEY-LOC PIC S9<4) COMP VALUE ?3, 

002100 77 REL0P Pic S9 ( 4 ) COMP VALUE 2, 

002200 77 KEVUENGTH PIC S9(4) COMP VALUE 8. 

002300 77 KEY, VALUE PIC X(B) VALUE "000-0000", 

O02400 01 DATA-sEC, 

002500 05 FILLER PIC XX. 

002600 05 NAME PIC X<20>. 

O02700 05 PhOnE PIC X(8), 

002800 05 OTHER-DATA PIC XU4), 

O029O0 01 FILETASLE. 

003000 02 FILENUMRFB PIC S9(4> COMP VALUE 0, 

003100 02 FILENAME PIC X(9> VALUE "GKSAMfIL". 

01)3200 02 I-O-TYPE Pic S9<4) COMP VALUE 0, 

003300 02 A-MooE PIC S9(4> COMP VALUE 0. 

003400 02 PREV-OP PIC S9(4) COMP VALUE 0, 

O03500 01 STATUSKEy. 

003600 02 STATUS-KFY-1 PIC X, 

O03700 02 STATuS-KEY-2 PIC X, 

003800 

OO3900 PROCEDURE OI v ISlON. 

00*000 START, 

004JOO CALL "CKOPFN" USING FILETABLE, STATUSKEY, 

o0*200 IF STATUS-KEY-1 = "9" TH£N 

004300 CALL "CkEHROR" USING STATUSKFY, RESULT 

004400 DISPLAY "CKOPEN ERROR NO, "» RESULT, 

00*500 IF STATUS-KEY-1 NOT a <>0'» THEN 

00*600 DISPLAY "CKOPEN FAILED" 

00*700 STOP RU\ , 

oo48oo jisplay "Alphabetical orderi" 

00*900 UISPLAy " ", 

no5ooo LooPi. 

005100 CALL "CKREAD" USING FILETa8LE> STATUSKEY. DATA-RECi 

005200 RECSIZE, 

O0&300 IF STATUS-KEY-1 s <■ 1 " THEN SO TO PAWT2. 
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fi05*0O U StATUS-Kfy-1 = "0" THEN 

105500 OTSPlAY DATA-REC 

005600 ELSE 

^05700 DISPLAY "CKREAO ERROR, STATUS * ", STATUSKEY 

oosaoo if status-key-i s »9» then 

o05<500 CALL "CKErrOR" using STATUSKEY, result 

OOfcOOO DISPLAY "ERROR NO, ", RESULT, 

nOblOO fc>0 TO LOO p ] , 

006200 PAHT2, 

006300 DISPLAY " •'. 

006400 uisplay ,,p hone no. orderi" 

006500 UISPLAy •• ». 

006600 CALL "CKSTflRTu USING FILETA8LE, STaTUSkEy, RELOP, 

006700 KEY-VALUE, KEY-LOC, KEYLENGTh, 

r»06800 IF STAtUSKfy = "23" THEN SO To FINISH. 

006900 IF STATUS-KEY-! = "0" THEN G<> TO L00P2, 

007000 PISPLAy "CKSTART ERROR, STATUS s 11 , STATuSKEY. 

007100 IF STATUS-KEY-1 = "9" THEN 

007200 CALL "CKERROR" USING STATUSKEY, RESULT 

007300 DISPLAY "FRrOr NO, ", RESULT, 

P07<.00 <>0 TO FINISH, 

007500 LOoP2, 

007600 CALL "CKREAO" USING FILETABLE» STATUSKEY, DATA-REC. 

007700 RECSlZE, 

007800 U STATuS-KfY-1 = "1" THEN GO TO FINISH, 

007900 IF ST*TuS-t<EY-l = "0" THEN 

008000 DISPLAY DATA-REC 

008100 ELSE 

008200 DISPLAY "CKREAO ERROR. STATUS a ", STATUSKEY 

008300 if STATUS-KEY-1 s "19" THEN 

008400 CALL "CKERROR" USI N G STATUSKEY, RESULT 

00 8 500 DISPLAY "ERROR NO, '■ , RESULT, 

OO860O 00 TO LOOPa, 

008700 finish, 

008800 call "ckclose" using filetable, statuskey, 

008900 IF STATUS-KEY-1 a "9" THEN 

009000 call "ckerror" using statuskey. result 

009100 display "ckclose error no. 

009200 STOP RUN. 



Figure 3-4. Sequential Read Using COBOL (continued) 
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Output from EXAMP2 Execution: 










alphabetical orderi 












CA9DIN 


RICK 


578-7018 


1U00 WOLFE ROAQ 


CUPERTINO 


CA, 


94 53 


EC<STEIN 


LEO 


287-5137 


5303 STEVENS CREEK 


SANTA CLARA 


CA, 


95050 


MOSODA 


JOE 


227-821* 


1180 SAINT PETER CT. 


LOS ALTOS 


CA, 


94022 


NOLAN 


JACK 


923„«975 


967 REED AVE. 


SUNNYVALE 


CA, 


94087 


PASBY 


LINDA 


295-H87 


Town s, cnTry village 


SAN JOSE 


CA. 


94102 


P09ERT 


SERRY 


2^9.5535 


1?345 TELEGRAPH AVE. 


BERKELEY 


CA, 


90871 


5EELY 


HENRY 


293.^220 


lift* LEBERTY ST. 


EL CERRITO 


CA. 


94053 


TU3NEWR 


Ivan 


984-849e 


??905 EMERSON ST, 


OAKLAND 


CA, 


98234 


WESTER 


ELDER 


287.4598 


1S56 KINGFISHER ST. 


SUNNYVALE 


CA, 


43098 


WHITE 


GORDON 


398-0301 


4350 ASHBY AVE. 


BERKELEY 


CA, 


91234 


phone no, r 


RDERI 












hOSODA 


JOE 


227-8214 


1180 SAINT PETER CT. 


LOS ALTOS 


CA, 


9402p 


ROBERT 


GERRY 


259-5535 


12345 TELEGRAPH AVE. 


BERKELEY 


CA. 


90871 


WESTER 


ELDER 


287. 4598 


1?56 KINSFISHER ST, 


SUNNYVALE 


CA, 


43098 


EC<STEIN 


LEO 


287-5137 


5303 STEVENS CREEK 


SANTA CLARA 


CA, 


95050 


SEELY 


HENRY 


293.4220 


1144 LEBERTY ST, 


EL CERRITO 


CA. 


94053 


PASBY 


LINDA 


295-1187 


TOWN & CNTRY VILLAGE 


SAN JOSE 


CA, 


94102 


WHITE 


GORDON 


398-0301 


4350 ASHBY AVE. 


BERKELEY 


CA. 


91234 


CA3DIN 


RICK 


578-7018 


11100 WOLFE ROAD 


CUPERTINO 


CA, 


94053 


NOLAN 


JACK 


923-4975 


967 REED AVE, 


SUNNYVALE 


CA, 


94087 


TURNEWR 


IVAN 


984.8498 


2g905 EMERSON St, 


OAKLAND 


CA, 


98234 


END OF PROGRAM 
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EXAMP3. RANDOM UPDATE 

This example reads a set of new data containing update information into the WORKING-STORAGE 
SECTION. Each record read is followed by a U for update, a D for delete, or an A for add. Records 
to be added are written to the file KSAMFILE using CKWRITE in random mode. Records to be 
updated are copied to the appropriate record with CKREWRITE. Records to be deleted are first 
read in the WORKING-STORAGE SECTION with CKREADBYKEY and then deleted with 
CKDELETE. The file is opened in random mode for input-output. 

The procedures illustrated by this example are: 

CKOPEN 

CKREADBYKEY 

CKDELETE 

CKREWRITE 

CKWRITE 

CKCLOSE 



Program 


EXAMP3: 




oolooo 


IDENTIFICATION DIVISION, 




001100 


PROGRAM-ID. EXAmPS, 




001200 


ENVIRONMENT DIVISION, 




001300 


INPUT-OUTPUT SECTION. 




001400 


FILE-CONTROL, 




001500 




SELECT NEW-DATA ASSIGN TO »*EWDATA», 


001600 


DATA DIVISION, 




001700 


FILE SECTIOM, 




001800 


FD 


NEW-DATA 




001900 




LABEL RECORDS ARE STANDARD, 




002000 


01 


INPUT-REc PIC X(73) , 




002100 


WORKING-STORAGE SECTION. 




002200 


77 


RECSIZE PIC S9U) COMP VALUE 


7*. 


002300 


77 


RESULT PIC 9<*) VALUE ZERO, 




002*00 


77 


KEY-LOC PIC S9U) COMP VALUE 


3. 


002500 


01 


MASTER-REC. 




002600 




05 FILLER PIC XX. 




002700 




05 NAME PIC X(20) , 




002800 




OS PHONE PIC X(8). 




002900 




05 OTHER-DATA PIC X<**>. 




003000 


01 


DATA-REC. 




003100 




05 NAME PIC X(20) , 




003200 




05 PHONE PIC X(8) , 




003300 




05 OTHER-DATA PIC X(**), 




003*00 




05 TRANSACTION-CODE PIC X, 




003500 


01 


FILETABLE. 




003600 




02 FILENUMBER PIC S9(4) COMP 


VALUE 0. 


003700 




02 FILENAME PIC X<8> VALUE 


"GKSAMFIL", 


003800 




02 I«0- T YPE PIC S9<4) COMP 


value a. 


003900 




02 A-MoDE PIC S9<*) COMP 


VALUE 1, 


00*000 




02 PREV-OP PIC S9<*t COMP 


value o. 


00*100 


01 


STATUSKEY. 




00*200 




02 STATUS-KgY-l PIC X, 




00*300 




02 STATUS-KEY-a PIC X. 




00**00 
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00*500 
00*600 
00*700 
004800 
00*900 
005000 
005100 
005200 
005300 
005400 
005500 
005600 
005700 
r)05800 
(105900 
O06000 
006100 
006200 
006300 
006400 
00&500 
006600 

00&700 
0O680O 
006900 
007000 
007IOO 
007200 
007300 
007400 
007500 
007600 
007700 
007800 
007900 
008000 
OO8100 
nO8200 
008300 
008400 
008500 
008600 
008700 

ooeaoo 

008900 
QO9000 
009100 
009200 
00*300 
009400 
009500 
009600 
009700 
00*800 
009900 
OlOOOO 

oloioo 

010200 
010300 
010400 
010500 

010600 
010700 

010800 
0109Q0 



procedure division, 
start. 

open input new-data. 

caul "ckopen" using filetable, statuskey, 

if status-key-i a 11911 then 

C*l_L "CkEHROR" USING STATUSKEY, RESULT 



LOqP. 



DISPLAY "CKOPEN ERROR NO, 
IF STAtUS-KEY-1 NOT .a "0" THEN 
DISPLAY "CKOPEN FAILED" 
STOP RUN. 



RESULT. 



IF 



MEAD NEW-DATA INTO DATA-RECJ 
AT END GO TO FINISH. 
TRANSACTION-CODE a "An THEN GO TO AOO-REC, 
IF TRANSACTION-CODE NOT a "D" AND "U" THFN 
DISPLAY "ILLEGAL TRANSACTION CODE" 
DISPLAY DATA-REC 
GO TO LOOP, 
CALL "CKREflDBYKEY" USING FILETABLE, STATUSKEY, MASTER-REC, 

NAME OF DATA-REC, KEY-LOC, RECSlZE, 
IF STATUS-KEY-1 NOT a "0" THEM 

DISPLAY "CKREADBYKEY ERROR, STATUS a », STATUSKEY, 

"» KEY a «, NAME OF DATA-REC 
IF STATUS-KEY-l a "9" THEN 

call "ckerror" using statuskey, result 
display "Error no, ", result 
go to loop 

ELSF 

Go TO LOOP. 
IF TRANSACTION-CODE a "D" THE N GO TO DELETE-REC, 
MOVE CORR DATA-REC TO MASTER-REC, 
CALL "CkREWRITE" USING FILETABLE, STATUSKEY, MASTER-REc, 

Recsize. 
if status-key-1 - "0" then 

display master-rec, " updated" 

GO TO LOOP, 
DISPLAY "CKQEWRITE ERROR, STATUS a » , STATUSKEY, tt f KEY a 1 

name of master-rec. 

IF STATUS-KEY-1 a "9" THEN 

call "ckerror" using statuskey, result 
display "error no, ", result 

Go TO LOOP. 
DELETE-REC. 

CALL "CKDELETE" USING FILETABLE. STATUSKEY, 
IF STATUS-KEY-1 a «»0" THEM 

DISPLAY MASTER-REC, » DELETED" 

SO TO LOOP, 
OISPLAy "CKDELETE ERROR, STATUS a .. , STATUSKEY, 
IF STATUS-KEY-1 s "9" THEM 

CALL "CKERROR" USING STATUSKEY. RESULT 

DISPLAY "ERROR NO, ", RESULT, 
GO TO LOOP. 
ADO-REC, 

MOVE CORR DATA-REC TO MASTER-REC, 

CALL "CKWRlTE" USING FILETABl-E, STaTUSKEY, MaSTER-REC, 

RECSIZe. 
IF STATUSKEY » "03" THEN 

DISPLAY "DUPLICATE KEY", 
IF STAtUS-KEY-1 a "0" THEM 

DISPLAY MASTER-REC, " ADDED" 

GO TO LOOP, 

DISPLAY "CKWRITE ERROR, STATUS ■ ", STATUSKEY, 
IF STATUS-KEY-l ■ "9" THEM 

CALL "CKERROR" USING STATUSKEY, RESULT 



DISPLAY "ERROR NO, 



RESULT. 
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OllOOO 
OlllOO 



OISPLAy MASTER-REC. 
60 TO LOOP, 

0I1200 finish. 

011300 close new-data, 

call "ckclosem using riletable, 

if status-key-1 * "9" then 

Call »»ckerror" using statuskey» result 

DISPLAY "CKCLOSE ERROR NO, m, 9ESULT. 
STOP RUN, 



011*00 
011500 
011600 
011700 

oiieoo 



STaTUSKEY, 



Input to EXAMP3: 



!*JOLAN 
ECKSTEIN 


JACK 

jOhfM 

LEO 


933-4975 
&5S-l?12 


I Amy STREET, 
102 FIRST ST. 


S.JMNiYVALE 
OUP TOWN 


CA. 
CA. 


9*0B7U 
9*099A 

1) 


C A K U I N 

paSBy 


WICK 

LlNU'C 


257-7000 


lllno WOL^E KOflO 


CUPFRTlNO 


CA. 


9«0l*U 

D 


JANE 

ROBERT 
TUHNEW 


MAWY 
GER^Y 

I VAIN 


565-90^0 
259-^535 


1776 BICENTENNIAL ST 
123*5 TELEGRAPH AVE. 


.ANAHEIM 
BERKELEY 


CA. 
CA . 


91076A 

n 


FOHD 


GE^LD 


5SS-1976 


1600 P£NnSYLVaMA 


WASHINGTON 


OC. 


20001U 


wtSTt* 


ELutK 


£87-4*98 


1256 KINGFISHER ST. 


SUNNYVALE 


CA 


.9A309A 



Output from Execution of EXAMP3: 



NOLAN 

SMITH 

EC<STEIN 

CA3DIN 

caSBY 

J«^E 

H03ERT 
Ck«E«DBYkEY 
CK«E»D9YKev 
CKwRITE ER» 

-ESTER 



JACK 
JOHN 
LEO 
PICK 
LINDA 
HARY 
GERFY 
ERRORi 
E3R0R, 
OB, STAT 
ELDE« 



923.4975 
555-1212 
287-5137 
2ST-700C 
2»S-JI8 7 
S65-9090 
2b9_ 5 53S 
STATUS ■ 23| 
STATUS ■ 231 
US = 22 

287-«£/.B 



1 ANY STREET. SUNNYVALE CA. 9* BT 

102 FIRST ST, OUR TOWN CA, 9*099 

5303 STEVENS C*»EEK SANTA CLARA CA. 95050 

lUOO WOLFE ROAO CUPERTINO CA, 9*01* 

TOWN I CNTRY VILLAGE SAN JOSE CA, 9*102 

1776 BICENTENNIAL ST. ANAHEIM CA, 910T6 

1?3*5 TELEGRAPH AVE. BERKELEY CA. 9*704 

KEY s TUftNEW I VAN 

KEY s FORD GERALD 

1256 KINGFISHER ST. SUNNYVALE CA. 9*309 



UPDATED 

ADDED 

DELETED 

UPDATED 

DELETED 

ADDED 

UPDATED 



Figure 3-5. Random Update with COBOL (continued) 



Note that the input contains data that results in error messages. The name IVAN TURNEWR is 
spelled incorrectly and cannot be found. The name GERALD FORD does not exist in the original 
file and also cannot be found. On the other hand, the name ELDER WESTER already exists in the 
file and cannot be added since it is a primary key for which duplicates are not allowed. 
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USING KSAM FILES IN SPL 

PROGRAMS 



SECTION 



IV 



KSAM FILE SYSTEM INTRINSICS 

The Multi-Programming Executive Operating System (MPE) provides a set of procedures, known 
as intrinsics. A subset of these intrinsics makes up the file system, a set of procedures used to 
manipulate files. KSAM files are processed using these same intrinsics with the following excep- 
tions: seven new intrinsics are added for KSAM files, and four of the file system intrinsics do not 
apply to KSAM files. (Refer to table 4-1 for a list of the KSAM file system intrinsics.) 



Table 4-1. KSAM File System Intrinsics 



INTRINSIC 
NAME 



FOPEN 

FCLOSE 
[FRENAME] 



FREAD 

*FREADC 

*FREADBYKEY 

FREADDIR 

[FREADSEEK] 



KSAM 
ONLY 



FWRITE 
[FWRITEDIR] 

*FREMOVE 
FUPDATE 



NOT USED 
BY KSAM 



X 
X 



X 



X 



X 



X 



DIFFERENCES IN FORMAT 



ksamparam replaces formmsg 
as sixth parameter. 



none 



none 



all new 



all new 



none 



FUNCTION 



Opens a KSAM file for 
access and assign file num- 
ber to file. 

Closes a KSAM file to 
further access. 

If called for KSAM file, re- 
turns CCL error code. 



control parameter included 
for compatibility only. 



all new 



none 



Reads next record in se- 
quential order by key. 

Reads next record in 
chronological sequence. 

Reads record identified by 
key value. 

Reads record identified by 
chronological position. 

If called for KSAM file, re- 
turns CCL error code. 



Writes record to KSAM file. 

If called for KSAM file, re- 
turns CCL error code. 

Deletes current record from 
KSAM file. 

Updates last referenced 
record. 



4-1 



Table 4-1. KSAM File System Intrinsics (continued) 



INTRINSIC 
NAME 



FSPACE 
*FFINDBYKEY 

*FFINDN 

FPOINT 



KSAM 
ONLY 



FGETINFO 

*FGETKEYINFO 

[FRELATE] 

FCHECK 
FERRMSG 



NOT USED 
IN KSAM 



X 



FCONTROL 



FSETMODE 



X 



FLOCK 
FUNLOCK 



FREADLABEL 
FWRITELABEL 



'HP32208 



X 



DIFFERENCES IN FORMAT 



all new 



all new 



none 



none 



all new 



none 



none 



param parameter included 
for compatibility only 



none 
none 



none 
none 



all new 



FUNCTION 



Spaces forward or backward 
in file. 

Positions current record 
pointer to record located 
by key value. 

Positions current record 
pointer to relative record 
number in key sequence. 

Positions current record 
pointer to relative record 
number in chronological 
sequence. 



Requests file access and 
status information. 

Requests access and status 
information on KSAM file. 

If called for KSAM file, re- 
turns CCE and false 
condition. 

Requests details of file 
input/output errors. 

Prints message correspond- 
ing to FCHECK error code. 



Ensures that input/output 
is complete or positions to 
first sequential record by 
key value; other options not 
available for KSAM file. 

Verifies critical output as 
part of write operation; 
other options not avail- 
able for KSAM file. 



Dynamically locks file. 
Dynamically unlocks file. 



Reads user's file label. 
Writes user's file label. 



Identifies the KSAM version. 
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CALLING INTRINSICS FROM SPL 

An intrinsic used in an SPL program must be declared at the beginning of the program following 
all other declarations. There are two ways to declare an intrinsic : one is to make an external pro- 
cedure declaration, and the other is to use the INTRINSIC declaration. Since declaring an external 
procedure is a long process, you can save space and time by using the INTRINSIC declaration as 
follows: 

INTRINSIC intrinsicname, intrinsicname, . . . ,intrinsicname; 

You name all the intrinsics used in your program in the intrinsicname list. When more than one 
intrinsic is named, the names must be separated by commas. 

You call an intrinsic by writing the intrinsic name followed by a list of parameters enclosed in 
parentheses. These parameters must be in the order established for each intrinsic as shown in the 
intrinsic formats later in this section. Every parameter that is specified as a variable or an array 
must be declared before the intrinsic is called. The formats that describe intrinsics define the 
variable or array type of each parameter; specify whether it can be passed by value or must be 
passed by reference; and indicate whether any parameters are optional and if so which ones. 

In summary, to call an intrinsic from an SPL program: 

1. Refer to the intrinsic format to determine the parameter type and position. 

2. Declare any variable or array names to be passed as parameters at the beginning of the program. 

3. Declare the intrinsic name in an INTRINSIC statement. 

4. Issue the intrinsic call where appropriate in your program. 

KSAM INTRINSIC SUMMARY 

Table 4-1 is provided to give an overview of the intrinsics available for accessing KSAM files. In 
this table, the intrinsics are organized into functional groupings. In the body of this section, how- 
ever, the intrinsic descriptions are in alphabetic order so that they may be referenced easily. 

In table 4-1, an asterisk (*) preceding an intrinsic name indicates that this intrinsic applies only to 
KSAM files. A bracket around an intrinsic name indicates that the intrinsic should not be used for 
KSAM files. 

INTRINSIC FORMAT 

Intrinsic format is illustrated below using FCHECK as an example. 

IV I I D I O-V 

FCHECK(filenum.errorcode,tlog,blknum,numrec); 
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Optional parameters are indicated by an underline under each option and by the superscript O-V. 
The parameter type and whether it is passed by value is shown by the superscript over each param- 
eter. Possible parameter types are: 

BA Byte array 

BP Byte pointer 

D Double 

DA Double array 

DV Double by value 

I Integer 

IA Integer array 

IV Integer by value 

L Logical 

LA Logical array 

LV Logical by value 

R Real 

PASSING PARAMETERS. Integer, logical and double type parameters can be passed by value. 
This means that the actual value can be specified in the intrinsic call instead of a variable or array 
name. When a parameter is passed by reference (default for all parameter types), the address in 
the caller's data area of the named variable or array is made available to the intrinsic. If the 
variable or array is modified by execution of the intrinsic, the storage in the caller's data area is 
updated. When a parameter is passed by value, the corresponding variable in the calling routine is 
unchanged. 

OPTIONAL PARAMETERS. If any parameters can be omitted, the superscripts that describe 
individual parameters are followed by the superscript O-V, option variable. O-V means that at 
least one parameter in the list is optional. Since all parameters are recognized by their position 
in the list, a parameter may be omitted but its preceding comma must be included. If one or 
more parameters are omitted from the end of the list, this is indicated by placing the terminating 
parenthesis after the last specified parameter. 

For example: 

FCHECK(FILEX , , , , REC) -* only the first and fifth parameters are included 

FCHECK(2,ERR) -« the last three parameters are omitted; note that filenum 

is passed by value. 
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KSAM RECORD POINTERS 



Certain KSAM procedures use pointers that indicate the current record position in the file. 
Depending on the procedure, either of two pointers may be used: 

• Logical Record Pointer Points to a key in the key file that identifies a 

particular record in the data file. 

• Chronological Record Pointer Points directly to a record in the data file based 

on its chronological record number. 

Procedures that use these pointers are either pointer-dependent or pointer-independent. Pointer- 
dependent procedures expect the pointer to be positioned in order to execute correctly. Pointer- 
independent procedures, on the other hand, execute regardless of where the pointer is positioned, 
and in most cases, they position the pointer. Because the position of the pointer is significant for 
pointer-dependent procedures, table 4-2 defines exactly where each pointer is located following 
successful execution of those procedures that either depend on or position the pointer. 

Table 4-2. Positioning the Pointers 



PROCEDURE 
NAME 


POINTER 
TYPE 


POINTER- 
DEPENDENT 


POSITION OF POINTER AFTER 
EXECUTION OF PROCEDURE 


FFINDBYKEY 


Logical 


NO 


Points to key whose value was specified in call. 


FFINDN 


Logical 


NO 


Points to key whose relative record number was 
specified in call. 


FREADBYKEY 


Logical 


NO 


Points to key whose value was specified in call. 


FWRITE 


Logical 


NO 


Points to key whose value is next in ascending key 
sequence to the key value in the record just written. 


FPOINT 


Chronological 


NO 


Points to record whose relative record number was 
specified in call. 


FREADDIR* 


Chronological 


NO 


Points to record whose relative record number was 
specified in call. 


FREAD 


Logical 


YES 


Pointer remains positioned to key for the record just 
read; unless next call is to FREAD or to FUPDATE 
followed by FREAD, in which case, pointer is 
advanced to next key in sequence before the next 
FREAD reads the record. (This permits sequential 
reads and updates.) 


F SPACE 


Logical 


YES 


Positioned forward or backward, in key sequence, 
the number of records specified in call. 


FREMOVE 


Logical 


YES 


Points to next key value, in ascending sequence, to the 
key value in the record just deleted. 


FUPDATE 


Logical 


YES 


Pointer remains positioned to key of the record just 
modified; unless any key value is changed, in which 
case, it points to next key in ascending sequence 
after the key in the modified record. 


FREADC 


Chronological 


YES 


Pointer remains positioned to the record just read; 
unless next call is to FREADC, in which case, it 
points to next record in ascending chronological 
sequence. 


* Except for FREADDI R, each of these procedures positions both pointers. That is, all procedures that position 
the logical pointer also position the chronological pointer, and all calls (except FREADDIR) that position the 
the chronological poiner also position the logical pointer. 



(Refer to appendix B, Extra Data Segments With Shared Access, for details of how KSAM determines 
pointer position.) 
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SHARED ACCESS 

The position of the record pointers is crucial during shared access because the pointers are main- 
tained in separate control blocks (extra data segments) for each open file. Thus, if the same file 
is opened by different users, any user may change the key file structure by adding or deleting 
records so that other users' pointers become invalid. To avoid this problem, it is good practice 
to lock the file in a shared environment before calling a procedure that positions the pointer and 
leave the file locked until any pointer-dependent operation is complete. This means that you 
should lock the file, call a procedure that sets the pointer, and then call a procedure that reads 
the file sequentially or updates the file, and then unlock the file so other users may access it. 
Once the file is unlocked, no user should assume that his pointers will still be valid. Before using 
a pointer again, it must be re-established. 
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FCHECK 

INTRINSIC NUMBER 10 



Requests details about file input/output errors. 



^v : i v r i ^ J) :?;•;>; A: i 

FCHECK(/ 'ilenum,errorcode,tlog,blknum,numrecs); 



O-V 



When a file intrinsic returns a condition code indicating a physical input/output error, additional 
details may be obtained by calling FCHECK. This intrinsic applies to files on any device. 

FCHECK accepts zero as a legal filenum parameter value. When zero is specified, the information 
returned in errorcode reflects the status of the last call to FOPEN. When an FOPEN fails, there is 
no file number that can be referenced in filenum. Therefore, when an FOPEN fails, a filenum of 
zero can be used in the FCHECK intrinsic call to obtain the errorcode only. If the tlog, blknum, 
or numrecs parameters are specified, a zero value is returned to these parameters. If a filenum of 
zero is used for a file which has been opened but not yet closed, the returned errorcode is 
meaningless. 



PARAMETERS 

filenum 



integer by value (required) 

A word identifier supplying the file number of the file for which error 

information is to be returned. 



errorcode 



tlog 



blknum 



numrecs 



integer (optional) 

A word to which is returned the error code specifying the type of error 
that occurred. If no error occurred errorcode is set to zero. (Refer to 
table 4-3 for the errorcode values.) The intrinsic FERRMSG returns 
a displayable message that corresponds to the value of errorcode. 

Default: The error code is not returned. 

integer (optional) 

A word to which is returned the transmission log value recorded when 
an erroneous data transfer occurs. This word specifies the number of 
words not read or written (those left over) as the result of an input/ 
output error. 

Default: The transmission log value is not returned. 

double (optional) 

A double word to which is returned the relative number of the block 

involved in the error. 

Default: The block number is not returned. 

integer (optional) 

A word to which is returned the number of logical records in the bad 

block. 

Default: The number of logical records is not returned. 
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CONDITION CODES 

CCE 
CCG 
CCL 



Request granted. 

Not returned by this intrinsic. 



Request denied because filenum was invalid and errorcode is 72, or a 
bounds violation occurred while processing this request and errorcode 
is 73. 



SPECIAL CONSIDERATIONS 

Split stack calls permitted. 



Table 4-3. FCHECK errorcode Parameter Format 



8 9 10 11 12 13 14 15 



FCHECK error code 



Shaded bits are set to zeros. 



Bits 
0:8 

8:8 



unused (all zeros) 

error code = one of the following values: 

Code 
(Decimal) 



Meaning 



End of file. 

1 Illegal DB register setting (typically, a request in split-stack mode when it is 
illegal). 

2 Illegal capability 

8 Illegal parameter value. 

20 Invalid operation. 

21 Data parity error. 

22 Software time-out. 

23 End of tape. 

24 Unit not ready. 

25 No write ring on tape. 

26 Transmission error. 

27 Input/output time-out. 

28 Timing error or data overrun. 

29 Start input/output (SIO) failure. 

30 Unit failure. 

31 End of line (special character terminator). 

32 Software abort of input/output operation. 

33 Data lost 

34 Unit not on line. 
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Table 4-3. FCHECK errorcode Parameter (continued) 



Code 
(Decimal) Meaning 



35 Data set not ready. 

36 Invalid disc address. 

37 Invalid memory address. 

38 Tape parity error. 

39 Recovered tape error. 

40 Operation inconsistent with access type. 

41 Operation inconsistent with record type. 

42 Operation inconsistent with device type. 

43 The tcount parameter value exceeded the recsize parameter, but the multi- 
record access aoption was not specified when the file was opened. 

44 The FUPDATE intrinsic was called, but the file was positioned at record zero. 
(FUPDATE must reference the last record read, but no previous record was 
read.) 

45 Privileged file violation. 

46 File space on all discs in the device class specified is insufficient to satisfy this 
request. 

47 Input/output error on a file label. 

48 Invalid operation due to multiple file access. 

49 Unimplemented function. 

50 The account referenced does not exist. 

51 The group referenced does not exist. 

52 The referenced file does not exist in the system (permanent) file domain. 

53 The referenced file does not exist in the job temporary file domain. 

54 The file reference is invalid. 

55 The referenced device is not available. 

56 The device specification is invalid or undefined. 

57 Virtual memory is not sufficient for the file specified. 

58 The file was not passed (typically, a request for $OLDPASS when there is no 
$0 LDP ASS). 

59 Standard label violation. 

60 Global RIN not available. 

61 Group disc file space exceeded. 

62 Account disc file space exceeded. 

63 Non-sharable device (ND) capability required but not assigned. 

64 Multiple RIN (MR) capability required but not assigned. 

66 Plotter limit switch reached. 

67 Paper tape error. 

68 System internal error. 

69 Miscellaneous (ATTACHIO) input/output error. 

71 Too many files opened for process. 

72 Invalid file number. 

73 Bounds check violation. 

77 NO-WAIT input/output operation is pending. 

78 There is no NO-WAIT input/output for any file. 

79 There is no NO-WAIT input/output for file specified. 

80 Configured maximum number of spoolfile sectors would be exceeded by this 
output request. 

81 No SPOOL class defined in system. 
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Table 4-3. FCHECK errorcode Parameter (continued) 





Code 






(Decimal) 


Meaning 




82 


Insufficient space in SPOOL class to honor this input/output request. 




83 


Extent size exceeds maximum allowable. 




84 


The next extent in this spoolfile resides on a device which is unavailable to 
the system (i.e., the device is =DOWN). 




85 


Operation inconsistent with spooling; e.g., attempt to read hardware status. 




86 


Spool process internal error. 




87 


Offset to data is greater than 255 sectors. 




89 


Power failure. 




90 


The calling process requested exclusive access to a file to which another 
process has access. 




91 


The calling process requested access to a file to which another process has 
exclusive access. 




92 


Lockword violation. 




93 


Security violation. 




94 


Creator conflict in use of FRENAME intrinsic (user is not the creator). 




95 


"BROKEN" terminal read. 




96 


Miscellaneous disc input/output error (device may require HP Customer 
Engineer attention). 




97 


CONTROL Y processing requested but no CONTROL Y PIN exists. 




98 


Input/output read time has overflowed. 




99 


Magnetic tape error. Beginning of tape (BOT) found while requesting a back- 
space record (BSR) or a backspace file (BSF). 




100 


Duplicate file name in the system file directory. 




101 


Duplicate file name in the job temporary file directory. 




102 


Directory input/output error. 




103 


System directory overflow. 




104 


Job temporary directory overflow. 




105 


Illegal variable block structure. 




106 


Extent size exceeds maximum allowable. 




107 


Offset to data is greater than 255 sectors. 




108 


Inaccessible file due to a bad file label. 




109 


Illegal carriage control option. 




110 


The intrinsic attempted to save a system file in the job temporary file 
directory. 




170 


FPOINT intrinsic tried to position to a record that was flagged for deletion. 




171 


Duplicate key value when duplicates not allowed. 




172 


Key not found; no such key value. 


Codes 170 — 


173 


tcount parameter larger than record size. 


200 


174 


Cannot get extra data segment for this file. 


Reserved 


175 


KSAM internal error. 


for KSAM 


176 


Illegal extra data segment length. 


File Errors 


177 


Too many extra data segments for this process. 




178 


Not enough virtual memory for extra data segment. 




179 


Undefined. 




180 


Undefined. 




181 


Invalid key starting position. 




182 


File is empty. 




183 


Record does not contain all the keys. 
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Table 4-3. FCHECK errorcode Parameter (continued) 




Code 






(Decimal) 


Meaning 




184 


Invalid record number in FFINDN intrinsic; record number is negative. 




185 


Sequence error in primary key. 




186 


Invalid key length; (numeric display and packed decimal type keys shorter 
than length specified at creation). 




187 


Invalid key specification; keys illegal. 




188 


Invalid device specification. 




189 


Invalid record format. 




190 


Invalid key blocking factor value. 




191 


Incorrect record; as a result of a previous system failure, a key points to a record 
that has a different key value. 




192 


System failure occurred when the KSAM file was open; run KEYINFO of 
KSAMUTIL to recover. 




193 


Undefined. 




194 


Undefined. 




195 


Undefined. 




196 


Undefined. 




197 


Undefined. 




198 


Undefined. 




199 


Undefined. 




200 


Undefined. 
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FCLOSE 

INTRINSIC NUMBER 9 
Closes a file. 



IV IV IV 

FCLOSE(filenum,disposition,seccode); 



The FCLOSE intrinsic terminates access to a file. This intrinsic applies to files on all devices. 
FCLOSE deletes the buffers and control blocks through which the user process accessed the file. 
It also deallocates the device on which the file resides and it may change the disposition of the file. 
If you do not issue FCLOSE calls for all files opened by your process, such calls are issued auto- 
matically by MPE when the process terminates. 



PARAMETERS 

filenum 
disposition 



seccode 



integer by value (required) 

A word identifier supplying the file number of the file to be closed. 

integer by value (required) 

Indicates the disposition of the file, significant only for files on disc. 
This disposition can be overridden by a corresponding parameter in a 
:FILE command entered prior to program execution. The disposition 
options are defined in table 4-4 

Default: disposition is zero for no change, no return of disc space. 

integer by value (required) 

Denotes the type of security initially applied to the file, significant 

only for new permanent files. The options are: 

— Unrestricted access — the file can be accessed by any user, unless 
prohibited by current MPE provisions. 

1 — Private file creator security — the file can be accessed only by its 
creator. 

Default: seccode is zero for unrestricted access. 

NOTE 

Both parameters are required when FCLOSE is specified in 
a program; the default values are used when MPE closes any 
open files at the end of a job or session. 



4-12 



FCLOSE 



Table 4-4. FCLOSE disposition Parameter Bit Settings 



10 



11 



12 



13 



14 



15 



Di*r 



Domain 



Set shaded areas to zero for KSAM files. 



BITS 



OPTION 



SETTINGS 



13:3 



Domain 



000 = No change, (default) The disposition code remains as it was before the 

file was opened. Thus, if the file is new, it is deleted by FCLOSE; other- 
wise, the file is assigned the domain to which it previously belonged. 

001 = Permanent file. If a disc file, it is saved in the system file domain. If 

the file is a new or temporary file, an entry is created for it in the sys- 
tem file directory. An error code is returned if a file of the same name 
already exists in the directory. This disposition has no effect when the 
file is an old permanent file on disc. 

010 = Temporary job file. The file is retained in the user's temporary (job/ 

session) file domain. It can be requested by any process within the job/ 
session. The uniqueness of the file name is checked and if a file of the 
same name already exists, an error code is returned. 

01 1 = Temporary job file. This option has the same effect as disposition code 

010. 

100 = Released file. The file is deleted from the system. 



12:1 



Disc Space 
Disposition 



No return, (default) Any disc space allocated to the file that is 
beyond the end-of-file indicator is not returned to the system. This 
option is recommended for KSAM files. 

Return disc space. Any disc space allocated beyond the end-of-file 
indicator is returned to the system. This option is not recommended 
for KSAM users since the returned space cannot be recovered. 



CONDITION CODES 



CCE 
CCG 
CCL 



The file was closed successfully. 

Not returned by this intrinsic. 

The file was not closed, perhaps because an incorrect filenum was 
specified, or because another file with the same name and disposition 
exists in the system. 
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SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FCLOSE 

The FCLOSE intrinsic terminates access to a file so that it cannot be accessed again by the current 
program until it is re-opened. FCLOSE can also be used to change the disposition currently assign- 
ed to a file by a previous FOPEN. 

Because of the special structure of KSAM files, it is not good practice to set the disc space bit in 
the disposition parameter in an attempt to save disc space. For this reason, 4 is the largest value that 
should be assigned to the disposition parameter when using FCLOSE to close a KSAM file. 

When a file is opened by the FOPEN intrinsic, a file count maintained by the system is incremented 
by one. When the file is closed with FCLOSE, the file count is decremented by one. If more than 
one FOPEN is in effect for a particular file, its disposition is recorded by the FCLOSE call but is 
not put into effect until the file count is zero. The effective disposition at that time is the smallest 
non-zero disposition parameter specified among all the FCLOSE calls issued against the file. For 
example, a file XYZ is opened three successive times by a process. The first FCLOSE disposition 
is 1, the second FCLOSE disposition is 4, and the third and last FCLOSE disposition is 2. The 
final disposition of the file XYZ is 1, that is, it is saved as a permanent file with no return of disc 
space. 

The use of FCLOSE differs slightly in its application to new files or to existing files. 

CLOSING A NEW KSAM FILE. When a new file is created by FOPEN, the job temporary and 
system file domains are not searched to determine whether a file of the same name exists already. 
Only when a file is closed and saved as a permanent or temporary file with FCLOSE, is such a 
search conducted. The job temporary file domain is searched if the file is closed with the domain 
field of disposition set to 2 or 3 (save as temporary file); the system file domain is searched if the 
file is closed with domain set to 1 (save as permanent file). If a file of the same name is found in 
either directory, an error code is returned. Thus it is possible to open a new file with the same 
name as an existing file, but an error results if FCLOSE is used to save such a file in the same 
domain with a file of the same name. 

In general, unless you plan to use the file once and then delete it, a newly created file should be 
closed using FCLOSE with the disposition parameter set to 1, 2, or 3. There is no need to set 
disposition to 4 in order to delete a new file since a new file is deleted when it is closed with a 
disposition of 0. 

The security code parameter (seccode) is set only when the disposition parameter is set to 1. If 
you want exclusive access to a file being saved as a new permanent file, you should set seccode to 
1 when you close the file for the first time. Otherwise, the file can be accessed by any other user. 

In figure 4-1, a new file is closed and saved as a permanent file in the system file domain 
(disposition = 1), and access is permitted to the file by other users (seccode = 0). 

CLOSING AN EXISTING KSAM FILE. Unless you plan to change the domain where a file is 
saved, you usually close an existing file with both FCLOSE parameters set to zero. There are two 
limitations: you cannot change an existing permanent file to a temporary file, and you cannot 
change the' security code that was assigned to a permanent file at creation. 
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<<* READ DATA FROM 5ST0IN DEVICE »>> 

Lli 

READ ( INPUT, -72) f <<READ ONE RECORD FROM *STDlN>> 

IF > 

THtN BEGIN <<END OF FILE ON $STDIN>> 

FCLOSE<FlC«l>M f i»a> f«CUOSE THE KSAMFTLE» 

BEGIN <<CANNOT CLOSE THE KSAM rj|.E» 

■■;■■.;- MES5A«t:stiCANViQT CLOSE THE KSAM flk 1 '! 
P «INT (MESSAGE* -29,0) I 

FCHECK <Fll-NUM,ERROHC<3nE) I <<5ET THE ERROR NUM6ER>> 

FERRMSG(ERRORCOOE, MEScft&E, LENGTH) |<<3ET MESSAfiE ST»f.NG>> 
PRINT(MfSSAt.E, -LENGTH, o) I <<PRINT ERRO** MESSA©E>> 

FNDj 
IF < 

then begin 

move message|s»ekpor occurred while reading input"! 

PRInT<MESSAGE,-3*iO) I 
TERMINATE! 
END} 
PRINT(OUTPUT,-72.0) | <<ECHq CHEC*>> 



Figure 4-1. FCLOSE Example 

Assume, for example, that a file was closed as a job temporary file. Should you want to make the 
file permanent, close the file with the following call: 

FCLOSE(FILENUM,1,0) close job temporary file as permanent file 

If, however, you want to maintain this file with its current disposition, you would close it with the 
following call; 

FCLOSE(FILENUM,0,0) close file with current disposition 

Regardless of the value assigned to seccode, the type of security initially applied to the file when it 
is closed as a new permanent file is not subsequently changed. 

DELETING A KSAM FILE. The FCLOSE intrinsic can be used to delete a KSAM file from the 
system. If you intend to use a new file once only, you can delete it at the same time you close it 
for the first time by setting the FCLOSE parameters to zero: 

FCLOSE(FILNUM,0,0) delete a new file 

In this case, because disposition is zero, the file is returned to its domain before FCLOSE is 
executed. Since the file is not assigned a domain until it is closed the first time, this effectively 
deletes the file. 
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A file that has been assigned to a domain by a previous FCLOSE, can be deleted by the call: 

FCLOSE(FILNUM,4,0) delete an existing file 

Note that the only other methods for deleting a KSAM file are to use the KSAMUTIL >PURGE 
command, or to issue two MPE :PURGE commands, one for the data file and one for the key file. 
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FCONTROL 

INTRINSIC NUMBER 13 



Performs control operations pn a KSAM file. 



IV IV L ' 

FCONTROl,(filenum,controlcode t param); 



The FCONTROL intrinsic performs various control operations on a KSAM file. When specified 
for a KSAM file, these control operations are limited to the following: 

• Complete input/output 

• Rewind the file 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file for which the 
control operation is to be performed. 

controlcode integer by value (required) 

An integer identifying the operation to be performed: 

2 = Complete Output. This insures that requested output has been 
physically completed; that is, that the key buffers, data buffers, and 
KSAM control information are all written to disc. 

When access is shared, you must lock the file with FLOCK before 
calling FCONTROL with control code 2. 

5 = Rewind File. This repositions the file at its beginning, so that the 
next record read or written is the first logical record in the file. When 
this code is used for KSAM files, the file is not repositioned to the 
first physical record but to the first logical record. The first logical 
record is the record with the lowest value in the current key (primary 
or alternate) 

6 = Complete Output/Write MPE EOF. This performs all the functions 
of control code 2 plus it writes the MPE end-of-file and the extent 

bit map to disc. (Note that the MPE end-of-file and the extent bit 
map are written to disc automatically whenever a new extent is 
allocated.) Writing the MPE end-of-file to disc periodically insures that 
it does not precede the KSAM end-of-file. Because the MPE end-of-file 
marker points to the next available block and the KSAM end-of-file 
marker points to the next available record within the last block, it is 
possible that the MPE mark is past the KSAM mark. 

In shared access, you must lock the file before calling FCONTROL with 
control code 6. 

7 = Clear Buffers. Clears the key and data buffers of all information, and 
then reads the KSAM control information (first two sectors of key file) 
from disc to the buffers. This forces data to be read from the disc to the 
buffers at the next read operation thereby insuring that the most up- 
to-date information is in the buffers. 
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In shared access, FCONTROL with control code 7 can be used 
immediately before a read operation, but this does not guarantee that 
the record read is not being modified or deleted by another user. For 
that purpose, you must use FLOCK (which also clears the buffers) 
before calling a read intrinsic. 

param logical (required) 

This parameter may be specified as any variable or word identifier; it 
is needed by FCONTROL to satisfy internal requirements of the 
intrinsic, but serves no other purpose and is not modified by the 
instrinsic. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. Returned if any control 

code other than 2, 5, 6, or 7 is specified for a KSAM file; or the file 
was opened for shared access, but was not locked for control code 
2 or 6. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FCONTROL 

FCONTROL provides four control functions for KSAM files. These allow you to write the key and 
data buffers and all KSAM control information to disc; to position the logical record pointer to the 
first logical record in the file; to write the buffers, KSAM control information, plus the MPE end- 
of-file and the latest extent bit map, to disc; and to clear all the data buffers and the latest control 
information from disc. 

The control functions that write the buffers to disc (2 and 6) require that you lock the file before 
calling them in a shared access environment. 

USING CONTROL CODE 2. When you use control code 2, the data block and key block buffers 
and the KSAM control information (including the KSAM end-of-file) are written to disc. (The 
data written is that contained in the Extra Data Segment for the open file — refer to figure B-ll for 
details.) This control code is particularly useful to make sure the KSAM file reflects current changes. 
Suppose, for instance, that you open a KSAM file exclusively for a long period of time and that 
your data buffer holds many records. In this case, you can call FCONTROL with code 2 after 
writing or updating a certain number of records to insure that no more than that number of records 
will be lost in case of a system failure. 

For example, you could call FCONTROL every 10 records: 

IF COUNT = 10 - counter set by each FWRITE or FUPDATE 

THEN BEGIN 

FCONTROL(FILNUM,2,DUMMY); 
END; 
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Note that the parameter DUMMY has no function. It is supplied because all 
FCONTROL parameters are required. It should be declared in the program as a 
word variable: LOGICAL DUMMY; 

As a result of the call shown above, you can never lose more than 10 records in case of a system 
failure. When a system failure occurs with a KSAM file open, you must run the KSAMUTIL 
command KEYINFO to allow the file to be reopened. KEYINFO also sets the MPE end-of-file 
to the current position of the KSAM end-of-file. Control code 2 of FCONTROL makes sure that 
the KSAM end-of-file follows the last record written to your file. 

In a shared environment, be sure to lock your file before calling FCONTROL with control code 2. 
Otherwise, the call will fail. 

USING CONTROL CODE 5. This control code repositions the file to the first logical record, 
that is, the record with the lowest key value. The key that determines this position can be the 
primary key or an alternate key, depending on which key was accessed last. Suppose you want 
to read the KSAM file in sequence starting with the record containing the lowest primary 
key value, you can position to this record using FCONTROL as follows: 

FCONTROL(FILNUM,5,DUMMY);- positions to 1st record in primary key sequence 

USING CONTROL CODE 6. This control code performs the same functions as control code 2, 
except that it also writes the MPE end-of -files for the KSAM files and the latest extent bit map 
to disc. Because it must access the MPE control blocks as well as the KSAM control block, this 
code takes more time than code 2. Also, since the MPE end-of-files and the extent bit map are 
written to disc automatically whenever a new extent is allocated, this code is useful primarily 
when a series of updates changes the buffers but does not cause new extents to be allocated, 
and when access to the file is exclusive. If access is shared, you must lock the file before using 
control code 6. 

USING CONTROL CODE 7. This control code clears the buffers so that the next call to a read 
instrinsic must get the record from disc rather than from the buffers. It also forces the latest 
control information to be read from disc to the buffers. Note that a call to FLOCK will also 
clear the buffers. The advantage of FCONTROL with code 7 over FLOCK is that it saves time 
— the buffers are cleared without locking and then unlocking the file. Thus, you can call 
FCONTROL with code 7 immediately before calling a read instrinsic in a shared environment in 
order to get the latest information from disc. However, this does not guarantee that this latest 
information is not changed (modified or deleted) by other users while you are calling FCONTROL. 
The only complete safeguard is to lock the file before the read. In any case, if you are making 
modifications, you should lock the file. For example: 

FCONTROL(FILNUM,7,DUMMY);— - — clear buffers 
FREAD(FILNUM,DATA,-72);« read record from file 



FLOCK(FILNUM,TRUE);- lock file 

FREAD(FILNUM,DATA,-72); 

FUPDATE(FILNUM,DATA,-72);- rewrite record just read 

FUNLOCK(FILNUM);- unlock file 
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Returns message corresponding to FCHECK error number. 

I LA I 

FERRMSG(errorcode, msgbuf, msglgth ) ; 

A call to FERRMSG causes a message to be returned to msgbuf that corresponds to an FCHECK 
error number. This makes it possible to display an error message from your program. The message 
describes the error associated with the error number provided in the parameter errorcode. 

PARAMETERS 

errorcode integer (required) 

A word identifier containing the error code for which a message is to 
be returned. It should contain an error number returned by FCHECK. 

msgbuf logical array (required) 

A logical array to which the message associated with errorcode is re- 
turned by FERRMSG. In order to contain the message string, msgbuf 
must be defined as at least 72 characters (36 words) long. 

msglgth integer (required) 

A word identifier to which is returned the length of the msgbuf string. 
The length is returned as a positive byte count. 

CONDITION CODES 

Condition codes are not returned by this procedure. 

USING FERRMSG 

This intrinsic is called usually following a call to FCHECK. The error code returned in the call to 
FCHECK can then be used as a parameter in the call to FERRMSG. 

For example, suppose a CCL condition is returned by a call to FCLOSE, a call to FCHECK requests 
the particular error code, then a call to FERRMSG can be used to retrieve a printable message asso- 
ciated with the code. 
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FCLOSE(FILNUM,1,0); 
IF< 

THEN BEGIN 

FCHECK(FILNUM,ERRNUM); 

FERRMSG(ERRNUM,MESSAGE,LENGTH); 

PRINT(MESSAGE,-LENGTH,0); 
END 
TERMINATE; 



The message printed explains the FCHECK code. If the FCHECK code has no assigned meaning, 
the following message is returned: 



UNDEFINED ERROR errorcode 
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INTRINSIC NUMBER 302 



Positions record pointer to record located by a key value. 

iv ba tv iv iv 

FFINDB YKE Y(filenum, key value, keyloca tion, key length, relop ) ; 



When FFINDBYKEY is executed, the logical record pointer is set to the beginning of a record 
located by this intrinsic. The particular key is defined by the keylocation parameter. The pointer 
is positioned to the first record containing a key value that bears the relation specified by relop to 
the value specified by keyvalue. A partial key can be specified by a keylength value less than the 
defined key length. If, however, the key type specified at file creation was numeric display or 
packed decimal, a type where the sign is stored in the least significant byte, partial keys cannot be 
specified. 

FFINDBYKEY also positions the chronological pointer. 



PARAMETERS 

filenum 
keyvalue 



keylocation 



keylength 



relop 



integer by value (required) 

A word identifier supplying the file number of the file to be positioned. 

byte array (required) 

A byte array containing a value that is used to locate the record at 
which the pointer is positioned. The key value in the record must be 
in the relation specified by relop to the value in array keyvalue. 

integer by value (required) 

The keylocation parameter specifies the relative byte location of the 
key being used. Bytes are numbered starting with 1. If keylocation 
is zero, then the primary key is used. 

integer by value (required) 

This parameter specifies the length of the key in bytes. If it equals zero, 
the entire key is used. If less than the full key length (generic key), then 
only the length specified here is used in the comparison with relop. The 
keylength parameter must be equal to or less than the full length of the 
key when the file was created. For keys of type numeric display or 
packed decimal, the full key length must be used. 

integer by value (required) 

A relational operator that specifies the relation of the key value in the 

file to the value specified in keyvalue. The record to which the file is 

positioned will have this relation to keyvalue following execution of 

FFINDBYKEY: 

— equal 

1 — greater than 

2 — equal to or greater than 

When relop is set to 1 or 2, the search is for an approximate key. 
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CONDITION CODES 

CCE Request granted. 

CCG The requested position was beyond the logical end-of-file or beginning 

of file. 

CCL Request denied because an error occurred. The error could be a disc 

input/output error; the relational operator (relop) could not be satis- 
fied; a keylength less than the full length was specified for a key 
with numeric display or packed decimal format; or a key is not 
found in the key file when the relational operator is equal. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FFINDBYKEY 

The intrinsic FFINDBYKEY allows you to position the file to a record containing a particular key 
value. Usually, you will do this in order to read in ascending sequence from that particular record. 
If you simply want to locate and read a single record, you should use FREADBYKEY. 

In figure 4-2, FFINDBYKEY is used to position the file to the record containing the lowest value 
of an 8-byte alternate key in which a telephone number is stored. After FFINDBYKEY positions 
the file to this record, a series of FREAD statements read the records in ascending order according 
to the value of the key specified by FFINDBYKEY. (Refer to shaded portions of the program for 
the FFINDBYKEY declarations and statements). 

FFINDBYKEY can also be used prior to a call to FREADC in order to position the chronological 
pointer to the record located by the specified key. 

USING APPROXIMATE KEYS. In order to find the lowest-valued telephone number, keyvalue 
is set to the value "000-0000". The key to be searched for this value is identified by its position 
in the record. In this case, the alternate key containing the telephone number starts in byte posi- 
tion 21, and keylocation is set to the value 21. The full length of the key is specified in keylength 
as the value 8. In order to position to the record whose alternate key value is equal to or greater 
than "000-0000", the value of relop is set to 2. 

When executed, FFINDBYKEY will locate the record with an 8-byte value starting in byte 21 
that is either equal to "000-0000" or is the lowest value greater than "000-0000". Since the 
value "000-0000" is not a valid telephone number, the value of relop could be set to 1 indicating 
the lowest value greater than "000-0000". An error condition is returned if the value in keyvalue 
cannot be located. For this reason, relop should not be set to unless it is expected that the 
value being sought exists. 
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USING PARTIAL (GENERIC) KEYS. If the value of keylength is less than the length of the key 
at creation, this allows a search for a partial (generic) key. For example, assume a file with a 20- 
byte key starting in byte 2 of each record. This key contains a name entered last name first. If 
you want to find and read all records starting with the letter "R" through the last record in se- 
quence by key, you could assign the following FFINDBYKEY values: 

INTEGER FILNUM; 

BYTE ARRAY FILNAME(0:9):="KSAMFILE "; 

BYTE ARRAY KEYVALUE(0:4):="R"; 

INTEGER KEYLENGTH:=1; 

INTEGER KEYLOCATION:=2; 

INTEGER RELOP:=2; 



INTRINSIC FOPEN,FCLOSE,FREAD,FWRITE,FFINDBYKEY ; 



FFINDBYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP) 

When executed, FFINDBYKEY will position to the first record with a key value whose first (left- 
most) character is the letter "R". A subsequent series of FREADs will read that record and posi- 
tion to the next record in sequence by the same key. 

SHARED ACCESS. If you use FFINDBYKEY to position the pointer before calling another 
procedure to read or update the file in a shared environment, you must call FLOCK to lock the 
file before calling FFINDBYKEY. Then, after performing the read or update operation, you 
can unlock the file. If you call FFINDBYKEY and then lock the file before an operation that 
depends on the record pointer, another user could move the pointer between the call to 
FFINDBYKEY and FLOCK. 
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<<* •>> 

<<» EXAMPLE P •>> 

<<« HEAR A KS.AM FILE SEQUENTIALLY »>> 
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Figure 4-2. FFINDBYKEY Example 
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Positions the logical record pointer to relative record number according to key sequence. 

IV DV IV 

FFINDN(/"{*ten«m, number, key location) 

When FFINDN is executed, it positions the KSAM logical record pointer to the record whose 
relative record number is specified in the parameter number. Records are numbered from the 
record with the lowest key value in the key that starts at keylocation in each record. Record 
numbering starts with zero unless the flagword in the FOPEN ksamparam parameter specifies 
that record numbering starts with 1, or the FIRSTREC parameter in the >BUILD command is 
set to 1. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be positioned. 

number double by value (required) 

Relative record number counting from the first logical record in the file. 
Record numbers start with zero or one depending on the record numbering 
scheme specified at file creation; the lowest numbered record applies to the 
record with the lowest value in the specified key field. A negative record 
number positions the file pointer to the record with the smallest key value. 

keylocation integer by value (required) 

The relative byte location in the record of the key to be used. The first 
byte is byte 1. If keylocation is set to zero, the primary key is assumed. 

CONDITION CODES 

CCE Request granted. 

CCG The requested position was beyond the logical end-of-file. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FFINDN 

When you specify the relative record number, it is important not to confuse this number with the 
chronological record number, the number of the record as it is stored in the file. To illustrate, 
assume a file in which records have been stored in chronological order from the beginning of the 
file (BOF). Each record has a key starting in byte 3 that contains a name. The relative record 
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number is based on the value of this key, not the relative location of the record in the 
file. 

For example: 

FFINDN(FILNUM,4D,3) 

This call positions the logical record pointer (as shown in figure 4-3) to record number 4 of the 
key at location 3. Note that record number 4 is the fifth record in the sequence of key values: 



ABLE 


relative record OD 


BAKER 


relative record ID 


CHARLIE 


relative record 2D 


DOG 


relative record 3D 


EASY 


relative record 4D 


FOX 


relative record 5D 



If you want to position the chronological record pointer to the relative record number in chrono- 
logical sequence from the beginning of the file, you can use the intrinsic FPOINT, discussed later 
in this section. Chronological order is the order in which records are written. In figure 4-3, record 
number 4 in key order, to which FFINDN positioned the file pointer, is also record number 2 in 
chronological order. 
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5 Key Order 



Figure 4-3. File Position with FFINDN 



Note that FFINDN is useful to reset the pointer to an alternate key. For example, when you 
open the file, the primary key is selected by default. If you want to select another key starting 
in location 23 and position to the first record in key sequence, you can use the following 
command: 

FFINDN(FILNUM,-1,23) 

SHARED ACCESS. If you use FFINDN to position the pointer before calling another procedure 
that reads or updates the file in a shared environment, you must call FLOCK before calling FFINDN. 
Then, after performing the read or update operation, you should unlock the file so other users can 
access it. If you lock the file after calling FFINDN, another user can change the pointer position 
without your program being aware of it. 
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INTRINSIC NUMBER 11 



Requests access and status information about a file. 

IV HA L L r 1 L L; 

FGETlNFO(filenum, filename y foptions , aoptions , recsize , devtype , ldnum ,hdaddr, 

f I) H D D D I L : 

filccodi recpt,t ■, flu U _ :. ■■■■ ■' ; ■; .-. .■ ■ -. • ....'.- .. :.-■. 



Once a file is opened on any device, the FGETINFO intrinsic can be used to request access and 
status information about that file. 



PARAMETERS 

filenum 
filename 



foptions 



integer by value (required) 

A word identifier supplying the file number of the file about which 

information is requested. 

byte array (optional) 

A byte array to which is returned the actual designator of the file 

being referenced, in this format: 

f.g.a 

where 

f = the local file name 

g = the group name (supplied or implicit). 

a = the account name (supplied or implicit). 

The byte array must be 28 bytes long. When the actual designator is 
returned, unused bytes in the array are filled with blanks on the right. 

Default: The actual designator is not returned. 

logical (optional) 

The foptions parameter returns seven different file characteristics by 
setting corresponding bit groupings in a 16-bit word. Correspondence 
is from right to left. The file characteristics returned are the same as 
those specified for foptions in the FOPEN intrinsic (refer to table 4-6, 
in the FOPEN description). Note that bit 4 is set to 1 to indicate a 
KSAM file. 



Default: Foptions are not returned. 
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aoptions 



recsize 



devtype 



Idnum 



logical (optional) 

The aoptions parameter returns up to seven different access options 

represented by bit groupings in a 16-bit word, as described for the 

aoptions parameter of FOPEN (refer to table 4-7 in the FOPEN 

description). 

Default: Aoptions are not returned. 

integer (optional) 

A word to which is returned the logical record size associated with the 
file. If the file was created as a binary type, this value is positive and 
expresses the size in words. If the file was created as an ASCII type, 
this value is negative and expresses the size in bytes. 

Default: The logical record size is not returned. 

integer (optional) 

A word to which is returned the type and subtype of device being used 

for the file, where 

bits (0:8) = device subtype, and 
bits (8:8) = device type. 

If the file is not spooled, which can be determined from hdaddr (0:8), 
the returned devtype is actual. The same is true if the file is spooled and 
was opened via logical device number. However, if an output file is 
spooled and was opened by device class name, devtype contains the 
type and subtype of the first device in its class, which may be different 
from the device actually used. 

Default: The device type and subtype are not returned. 

logical (optional) 

A word to which is returned the logical device number associated with 

the device on which the file resides. 



If the file is a disc file, then the logical device number will be that of the 
first extent. If the file is spooled, then Idnum will be a virtual device 
number which does not correspond to the system configuration I/O 
device list. 



hdaddr 



Default: The logical device number is not returned. 

logical (optional) 

A word to which the hardware address of the device is returned, where 

bits (0:8) = the Device Reference Table (DRT) number, and 
bits (8:8) = the unit number. 

If the device is spooled, the DRT number will be zero and the unit 
number is undefined. 



Default: The hardware address is not returned. 
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filecode 



integer (optional) 

A word to which is returned the value recorded with the file as its data 

file code (for disc files only). 



Default: The file code is not returned. 



recpt 



double (optional) 

A double word to which is returned a double integer representing the 
current chronological record pointer setting. This is the displacement in 
chronological records from record number in the file. This record 
number is counted from the first record stored in the file in chronologi- 
cal order; it is not the logical record number counting from the lowest 
key value in ascending sequence. The pointer setting (recpt) identifies 
the record that would be accessed next by an FREADC intrinsic. 



eof 



Default: The chronological record pointer setting is not returned. 

double (optional) 

A double word to which is returned a double positive integer equal to 
the number of logical records currently in the data file. If the file does 
not reside on disc, this value is zero. 



flimit 



Default: The number of logical records in the file is not returned. 

double (optional) 

A double word to which is returned a double positive integer represent- 
ing the number of the last logical record that could ever exist in the 
data file because of the physical limits of the file. 



logcount 



Default: The file limit information is not returned. 

double (optional) 

A double word to which is returned a double positive integer represent- 
ing the total number of logical records passed to and from the user 
during the current access of the file. 

Default: The logical record count is not returned. 



physcount 



double (optional) 

A double word to which is returned a double positive integer represent- 
ing the total number of physical input/output operations performed 
within this process against the file since the last FOPEN call. 



Default: The number of I/O operations is not returned. 



blksize 



integer (optional) 

A word to which is returned the block size associated with the file. If 
the file was created as a binary type, this value is positive and expresses 
the size in words. If the file was created as an ASCII type, this value is 
negative and shows the size in bytes. 



Default: The block size is not returned. 
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extsize 



numextent 



user labels 



creatorid 



labaddr 



logical (optional) 

A word to which is returned the disc extent size associated with the 

data file (in sectors). 

Default: The disc extent size is not returned. 

integer (optional) 

A word to which is returned the maximum number of disc extents 

allowable for the data file. 

Default: The maximum allowable number of extents is not returned. 

integer (optional) 

A word to which is returned the number of user header labels defined 
for the file when it was created. When an old file is opened for over- 
write output, the value of userlabels is not reset and old user labels 
are not destroyed. 

Default: The number of user labels is not returned. 

byte array (optional) 

A type array to which is returned the eight-byte name of the user who 

created the file. If the file is not a disc file, blanks are returned. 

Default: The user name is not returned. 

double (optional) 

A double word to which is returned the sector address of the label of 
the file. The high-order eight bits show the logical device number. 
The remaining 24 bits show the absolute disc address. 

Default: The label address is not returned. 



CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

USING FGETINFO 

By calling FGETINFO you can return to your program any or all of the items listed as parameters. 
Except for the identifying filenumber, each of these parameters is optional. When omitted, em- 
bedded parameters are indicated by commas. Parameters omitted from the end of the list need not 
be so indicated. For example, to locate the number of records in the file by finding the end of file, 
you can call FGETINFO as follows: 



FGETINFO(FILNUM ,,,,,,,,,, LSTREC); 



eof parameter 
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The value returned to LSTREC is the number of records in the file. The value LSTREC is also 
the chronological number of the last record in the file. This number can be used to read the 
last chronological record with FREADC or FREADDIR. 

Another useful parameter of FGETINFO is recpt. This parameter returns the chronological record 
number of the record last read. The example in figure 4-4 illustrates both these parameters. First, 
FGETINFO is used to determine the total number of records in the file using the parameter eof. 
Then, each record in the file is read in sequential order by primary key. Following each sequential 
read, FGETINFO retrieves the chronological record number of the record just read. 

In the output from the program (refer to figure 4-4), note that the record number returned by 
FGETINFO is the chronological number. For instance, the first record written to the file was the 
record with record number 1. This record, which contains the primary key value "NOLAN JACK", 
is the fourth consecutive record in key sequence. 
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HCO^HOl. MAlN=jEXAMPL5 

«• »" 

<<a EXAMPLE 5 «>> 

, <lt KIND NUM c iE« OF RLCoWUS K RECORD NUMBER «>> 

«* *» 

Ii>rr;.E:R t«»»Of«CODt .LENGT^l 

BVTE APWftV FlLNAME<01-*>:*'"Jt;xA»F IL "I 

AR^Ay MESSAGE (0!J5) | 

ARnIV INPUT(o!39)J 

it,S» OUTPUT (O) sINPuT I 

-OPEN, FCLOSEr^ BEAD, F6ETlNFO,0ASCtl» 

p x i - .- =--•:■- - -.,-•".-'. - . - i ----- 1 

<<n«t«o»»»»i>»»»"«»« , '» ,,,,,l >>> 
<<o OPEN THE KSAM FILE «>> 

<<»#0»«O»(Ht»»*»«»°«»****«*>> 

Fl|_N JM;=F0PEN(FILNAME,3) I <<OPEN THE KSAM flLl>> 

IF FILNUM = ') 

ThtN BEGIN <<CANNOT OPEN KSAM FILF.>> 

MOVE MESSAGEl*"CANNOT OPEN KSAM FILE"» 
PHINT(MESSAGEi-21iO) I 

FCMECK(FILNUM,ERHORCODE) I <<GET ERROR NUMBFR>> 
FE«RMSG(ERRORCODt, MESSAGE, LENGTH) |<<CONVE«T To STRJ.NG>> 
PRINTIMESSAGEt-UtNGTM.O) I <<PRINTOUT ERROR MESSAGE>> 
TERMINATE* 
FND| 

«< *IM0 NUMftefi 6f. ft£CO«OS '• KH'ltTEN TO PILE »>> 

illliill^^ 

t*-en peg:* 

MOVE M£5SA6£ j,«Mfc«ROR oCCUR«EO ' f INQXNG- NUMBER Of «EGOW>$" I 

FEHWMS'j EP« :-■■„■:.•■ ■ Ml ^-•,i--.L.„ r '- »TH) ; 
PPl-MTt MESSAGE, -i-tN&TH,0 ,f 

c< " V PRI • .,*->-■• OF ~E....>r 3 IN t*_-; *>» 

Pt*I'"T (MESSAGt,-£O»0) I 
LI I 

<<<t READ KSAM SEQUENTIALLY «>> 

<<«»tn>*»«*«*»»»***» »•••••»•• »••••••••••#•• •»»»•»»»»•»•>> 

FREAD(FlLNUM» INPUT, -721 I 

IF > <<ENO OF DATA>> 

ThEN BEGIN 

FCLOSE(FlLNUM,0,0) | <<CLOSE THE KSAM Fj.LE>> 

IF <> THEN 
9FGIN 

MOVE MESSAGt IsmCAnNOT CLOSE THE KSAM FILE"I 

PRINT IMESSAbE, -22,0) I 

FCHECK(FlLNUM,ER«ORCPDE) I <<GET ERROR NUMBER>> 
FERRMSGfERHORCOOE, MESSAGE, LENGTH) |<<C0NVERT TO STRInG>> 
PRINT (MfSSAliE, -LENGTH, 0) | <<PRtNTOUT EPROR MESSAGE>> 

EnU» 
TeRmINAtEi 
END| 



Figure 4-4. FGETINFO Example 
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IF < 

THEN BEGIN 

MOVE MESSAGE sa"tHHOR OCCURRED WHILE READING *SAM FILE"! 
PRINT (MESSAGEi-37,0) I 

FCHECK<rlLNUM,ERRORCODE) | <<GET ERROR NUMRER>> 
FERRMSG(ERRORCODt, MESSAGE, LEMQTH) |<<CONVERT To STRING>> 
PRINT (MfSSAGEi-LtNGTH, 0) I <<PRINTOUT ERROR MESSAGE>> 
TERMINATE) 
END| 

<<» WRITE THE DATA JUST READ FROM KSAM FILE #>> 

PRINT (OUTPuTi-72i0) | 

<<u«oa»«««o««»»»s««o«««<»««««*«»««<»oi>««»»»e»«»»»aae«»»»o>> 
<<» TO FINO OUT RECORO NUMBER QF THE RECORD JUST READ o>> 
<<o««»i>i>oi>o«««»i>e«««e««»»«oa»»«»«»««««i>»o»»«*«<>»»fto»«»«>> 

F5fcTINFO(FILMUM, ,,,,„,, RECPTR ) I 

; EtV.c.*.^ -',U j\: J V- ;, •' ,',_•■ ; ' ■ ; -/V- 4-t, r . -•/;, ' . ,',',■: \ "?; ,/■"" =•;"; V.;- -;■;,,. . ': ■■■• \ ; ," .' '. ■ • - : _ : : ; " ":"■■_ ■■■ ;; ".; ,VV>: V' 
T»-EN 3ESJN 

MOVF MESSAGE |="EHROrt OCCUPPfO FINDING HECORD NUMBER"! 

■'■■> I .-I (MESS A ;p, -JO,0) ( 

FC H ECK(Fll_NUM, E«K[ ■:.■■■.-■_>; : | 

Fffi :---■ * ■ ERHORCOUL,* ESSAGF . lFNGTm) i 

.- -•'■.:■ IMF . SAGF ,"i.f N&TH ; . ; 

TERMINATE I 

<<» 3PINT THE RECORD NUMBER OF L fl ST RECORD READ »>> 
■: 4 . >««•«»•••••••••••••••< »«a»»oeeee»ee»00«eo»ee<»>? 

ESSA 3fc !s"RECORD* '• " j 

^•KTI fRECPT«, 10»MESSA<i£ CSS J > 
PHINTiMrg^^bE.-laiO) f 

<<o GO B1CK TO GET ANOTHER RfCORn »>> 

«C T3 LI I 
EM; I 
JEOl 

When Executed, the Following Output is Printed: 



RECORDS 


■ . " " :■ .-. 


CARDTN 




PICK 


RECOPD* 


= 


4 


ECKSTEIN 


LEO 


RECOPD* 


i 


WQR. :,,, 


HHSOOA 




JOE 


RECORD* 


= 


? 


NOLAN 




JACK 


RECORD* 


.. 


'.I '*-•'':';" 


PASBY 




MNDA 


RECORD* 


- 


5 


ROBERT 




GERRY 


RECORD* 


= 


7 


SEELY 




HENRY 


RECOPD* 


.-. 


6 


TIJRNEWR 




TVAN 


RECORD* 


= 


H 


MESTEP 




ELDER 


RECORD* 


= 


10 


WHTTE 




GOPDON 


RECOPD* 


; 






10 



57R-7018 11100 WOLFF ROAD CUPERTINO CA. 94053 

287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050 

227-B214 1180 SAINT PFTFR CT. LOS AI.TOS CA. 94022 

923-4975 967 REED AVE. SUNNYVALE CA. 94087 

295-1187 TOWN & CNTPY VILLAGE SAN JOSE CA. 94102 

259-5535 12345 TELEGRAPH AVE. BERKELEY CA. 90871 

293-4220 1144 LEBFRTY ST. EL CFPPITO CA. 94053 

"84-8498 22905 FMERSON ST. OAKLAND CA. 98234 

287-4598 1256 KINGFISHER ST. SUNNYVALE CA. 43098 

398-0301 4350 ASHPY AVE. BEFKF.LFY CA. 91234 



END OF PROGRAM 



Figure 4-4. FGETINFO Example (continued) 
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INTRINSIC NUMBER 303 



Requests access and status information about a KSAM file. 



FGETKEYlNFO(filenum, ksamparam, ksamcon trol) 



PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the filenumber of the file about which 
information is requested. 

ksamparam array (required) 

An array of the same format and size as the byte array of the same 
name in FOPEN (refer to table 4-8), except that key file size is given 
as the number of sectors. The length of the array depends on the 
number of keys in the KSAM file; its length is 17 words plus 4 words 
for each key. Note that the device (words 6-14) is not returned as a 
device class name but as an ASCII string containing the logical device 
number. 

ksamcontrol array (required) 

an array whose size is 128 words containing control information about 
the key file. Refer to table 4-5 for the definition of the array contents. 

CONDITION CODES 

CCE Request granted. 

CCG (not returned) 

CCL Request denied because an error occurred such as: insufficient space 

declared for ksamparam or ksamcontrol; or an illegal file number; or 
the DB register is not set to the user stack. 

USING FGETKEYINFO 

Once a KSAM file is opened, you can request information about the key file through this intrinsic. 
The ksamparam return provides static information defined for the key file at the time it was 
created. The ksamcontrol parameter provides dynamic information about the use of the key file 
from the time it was created. In particular, it provides a count of the number of times the key file 
was referenced by various intrinsics, the date and time it was created, closed, updated or written 
to, and so forth. 
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Table 4-5. FGETKEYINFO ksamcontrol Parameter Format 



BIT/ 
WORD 



10 

13 

16 

17 

18 

20 

22 

23 

24 

25 

27 

29 

31 

33 

35 

37 

39 

41 

43 

45 

47 

49 

51 

53 



1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 



Data File Name (8 bytes) 



year 



day 



hour 



second 



year 



minute 



second/ 10 



day 



hour 



second 



year 



minute 



second/10 



day 



hour 



second 



year 



minute 



second/ 10 



day 



hour 



second 



Version (ASCII letter) 



minute 



second/10 



Update no. (binary) 



Fix level (binary) 



Number of records in data file (double word) 



Number of blocks in data file (double word) 



Number of words in last block of data file 



Number of words in data file block 



Number of bytes in data file record 



FOPEN count (double word) 



FREAD count (double word) 



FCLOSE count (double word) 



FREADDIR count (double word) 



FREADC count (double word) 



FREADBYKEY count (double word) 



F REMOVE count (double word) 



FSPACE count (double word) 



FFINDBYKEY count (double word) 



FGETINFO count (double word) 



FGETKEYINFO count (double word) 



FREADLABEL count (double word) 



FWRITE LABEL count (double word) 



FCHECK count (double word) 



FFINDN count (double word) 



/ 



Last key file creation (set 
by>BUILD) 

Last key file close (set by 
FCLOSE) 

Last key value change (set 
by FUPDATE or FWRITE) 

Last count reset (set at 
create or by >ERASE) 

. KSAM/3000 version number 
at file creation (use HP32208 
intrinsic to get current version 
of KSAM/3000) 



Counts reflect total number 
of times file has been 
accessed by each intrinsic 
since file was last created 
or erased (see words 4-6 for 
date and time of creation). 



/ 
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Table 4-5. FGETKEYINFO ksamcontrol Parameter Format (continued 



BITS/ 
WORDS 

55 
57 
59 
61 
63 
65 
67 
69 
71 
73 
75 
76 
77 
78 

80 
81 
82 
84 
86 
88 
90 
92 
94 
95 
96 



1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 



FWRITE count (double word) 



FUPDATE count (double word) 



Any key block read count (double word) 



Any key block write count (double word) 



Any key block split count (double word) 



Next available key block record number (double word) 



Reserved for future use (double word) 



Minimum primary key value record number (double word) 



Maximum primary key value record number (double word) 



Reserved for future use. 



Data file record type (fixed=TRUE) 



Data file blocking factor 



Total number of keys (always >0) 



Counts reflect total number 
of times file has been 
accessed by each intrinsic 
since file was created or 
erased. 



Record numbering method (double word) 
(= -1 D if starts with 1 , 0D if 0) 



Minimum record size* 



Current accessors (+1 for open, -1 for close) 



FPOINT count (double word) 



FLOCK count (double word) 



FUNLOCK count (double word) 



FCONTROL count (double word) 



FSETMODE count (double word) 



File Limit (double word) 



Keyblock size 



Key block buffer size in extra data segment 



Delete head for free key blocks (double word) 




Key file size (No. of sectors) (double word) 



Reserved for future use 



"The minimum record size is the minimum size in which all keys are contained; it is computed by taking the 
highest key location, adding the key length, and subtracting 1 : 

min record = max key position + keylength -1 
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INTRINSIC NUMBER 15 



Dynamically locks a file. 



IV LV 

FLOCK(filenum, lockcond); 

The FLOCK intrinsic dynamically locks a file and transfers the latest control information from 
disc to the buffers. A call to FLOCK is required before any attempt is made to read or modify a 
file opened for shared access. 



PARAMETERS 



filenum 



lockcond 



integer by value (required) 

A word supplying the file number of the file to be locked. 

logical by value (required) 

A word specifying conditional or unconditional locking: 

TRUE — Locking will take place unconditionally. If the file 
cannot be locked immediately, the calling process 
suspends until the file can be locked. 

Bit 15 = 1 

FALSE — Locking will take place only if the file's Resource Identifi- 
cation Number (RIN) is not currently locked. If the RIN 
is locked, control returns immediately to the calling 
process, with condition code CCG. 

Bit 15 = 



CONDITION CODES 

The condition codes possible when lockcond = TRUE are 



CCE 
CCG 
CCL 



Request granted. 

Not returned when lockcond = TRUE. 

Request denied because this file was not opened with the dynamic 
locking aoption specified in the FOPEN intrinsic, or the request was to 
lock more than one file and the calling process does not possess the 
Multiple RIN Capability. 



The condition codes possible if lockcond = FALSE are 



CCE 
CCG 
CCL 



Request granted. 

Request denied because the file was locked by another process. 

Request denied because: this file was not opened with the dynamic 
locking aoption specified in the FOPEN intrinsic; or the request was 
to lock more than one file and the calling process does not possess the 
Multiple RIN Capability. 
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SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

Standard Capability sufficient if only one file is to be locked dynamically. 

If more than one file is to be locked dynamically, the Multiple RIN Capability is required. 

USING FLOCK 

The dynamic locking and unlocking capability allows you to complete any update to a file when it 
is possible for other users to access the file. When dynamic locking is allowed (bit 10 of FOPEN 
aoptions parameter is set to allow dynamic locking) ; then you must use the FLOCK intrinsic to lock 
the file before writing, rewriting, or deleting any records. This requirement insures that another user 
does not attempt to change the same record at the same time. FLOCK also insures that the most 
recent data is available in the file. A locked file can be unlocked following the update with the 
FUNLOCK intrinsic. 

When FLOCK is executed, it clears all the buffers and transfers the latest control information from 
the KSAM file to the buffers. This insures that any subsequent read of the file retrieves the latest in- 
formation from disc rather than from the buffers. (Note that FCONTROL control code 7 also clears 
the buffers.) 

If you use the Multiple RIN capability, a sequence of file locking should be agreed upon or you 
should use conditional locking (lockcond = FALSE). Otherwise, it is possible to lock other users 
from the file. Consider the situation where one program unconditionally locks file A and then 
attempts to lock file B. If another program unconditionally locks file B and then attempts to lock 
file A, both programs will wait indefinitely to lock the second file in sequence. To avoid this, both 
programs should agree to lock the files in the sequence A first, then B; or both programs should 
use only conditional locks. 

For example, suppose you open a KSAM file called DATA1 for shared access in update mode and 
allow dynamic locking and unlocking: 

FILl:=FOPEN(DATAl,7,%345); 

The parameters specified are: 

filenum File number of DATA1, which is assigned to FIL1 when the file is 

opened. 

formaldesignator Name identifying the file contained in DATA1. 

foptions The value 7 specifies that this is an old user file (bits 14,15 = 11) and 

that it is coded in ASCII (bit 13 = 1). 

aoptions The octal value 345 indicates that the file was opened for update 

(bits 12 through 15 = 0101), that dynamic locking/unlocking is allowed 
(bit 10 = 1), and that access is shared (bits 8 and 9 = 11). 



4-39 



FLOCK 



This file can then be locked as follows: 

FLOCK(FILl,l) 
The parameters specified are: 
filenum File number of file DATA1 contained in the variable FILL 

lockcond = 1 which means the file is to be locked unconditionally. If the file 

cannot be locked immediately, the calling process is suspended until 
the file can be locked. 
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INTRINSIC NUMBER 1 



Opens a file. 



<SX " 1 BA LV I .V IV BA BA 

fUenum:=FOPEN(formaldesignaton foptions , aoptions y recsize , device , ksamparatn , 

in itiaUoc. f t Icro de ~> ; 



The FOPEN intrinsic makes it possible to access a KSAM file. In the FOPEN intrinsic call, a 
particular file may be referenced by its formal file designator. When the FOPEN intrinsic is exe- 
cuted, it returns to the user's process a file number by which the system uniquely identifies the 
file. This file number, rather than the file designator, then is used by subsequent intrinsics in 
referencing the file. 

FUNCTIONAL RETURN 

This intrinsic returns an integer file number used to identify the opened file in other intrinsic calls. 



PARAMETERS 

formaldesignator 



byte array (required) 

Contains a string of ASCII characters interpreted as a formal file 
designator. This string must begin with a letter, contain alphanumeric 
characters, slashes, or periods, and terminate with any non-alpha- 
numeric character except a slash or a period. If the string names a user- 
predefined file, it can begin with an asterisk (*). Note: The DEL, SAVE, 
or TEMP parameters should not be used to predefine a KSAM file in a 
:FILE command; they will cause deletion or duplication of the file. 



foptions 



aoptions 



logical by value (optional) 

The foptions parameter allows you to specify different file character- 
istics, by setting corresponding bit groupings in a 16-bit word. If the 
file is new, bit 4 must be set to 1 to indicate that this is a KSAM file. 
Refer to table 4-6 for the foption bit settings. 

Default: All bits are set to zero. 

logical by value (optional) 

The aoptions parameter permits you to specify the various access 
options established by bit groupings in a 16-bit word. These access 
options are defined in table 4-7. 

Default: All bits are set to zero. 
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recsize 



integer by value (optional) 

An integer indicating the size of the logical records in the data file. 
If a positive number, this represents words; bytes are represented by a 
negative number. If the file is a newly-created file, this value is re- 
corded permanently in the file label. If the records in the file are of 
variable length, this value indicates the maximum logical record length 
allowed. 



device 



Binary files are word oriented. A record size specifying an odd byte 
count for a binary file is rounded up by FOPEN to the next highest 
even number. 

ASCII files may be created with logical records which are an odd num- 
ber of bytes in length. Within each block, however, records begin on 
word boundaries. 

For either ASCII or binary files with fixed-length records, the record 
size is rounded up to the nearest word boundary. For example, a 
recsize specified as -106 for an ASCII file is 106 characters (53 words) 
in length. A recsize of -113 for a binary file is 114 characters (57 
words) in length. The rounded sizes should be used in computations 
for blockfactor or block size. 

Default: The default value is the configured physical record width of 
the associated device. 

byte array (optional) 

Contains a string of ASCII characters terminated by any non- 
alphanumeric character (except a slash or period) that designates 
the device on which the file is to reside. It may be a device class 
name of up to eight alphanumeric characters beginning with a letter; 
or a logical device number consisting of a three-byte numeric string; 
or a remote device identifier consisting of the device class name or 
logical device number followed by a pound sign (#) and a remote de- 
vice class name or logical device number. 

Device class names and logical device numbers are assigned to devices 
during system configuration. 

For KSAM files, the device must be a random access device such as 
the disc. If the file is a newly-created disc file specified as a device 
class name, then all extents to the file must be members of the same 
class. Similarly, if the device is identified by logical device number, 
then all extents must have the same logical device number. 

Default: Disc. 



ksamparam 



byte array (optional) 

Contains information describing the key file of a KSAM file. It 
includes the key file name, size and device plus an entry for the 
primary key and up to 15 alternate keys. If the file is new (is being 
created by FOPEN) then this array must be included. If the file is 
an old file, it can be omitted. Note that if the parameter is included 
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userlabels 



blockfactor 



and the file is not a KSAM file, an error can result. Refer to table 
4-8 for a full description of ksamparam. 

Default: key file description is omitted. 

integer by value (optional) 

Specifies the number of user-label records to be written for the data 

file. If there are no user labels, this parameter can be omitted. 

Default: The default number of user-label records is zero. 

integer by value (optional) 

Establishes the size of each block in the data file by specifying the 
number of logical records per block. It also establishes the size of the 
data file buffer in KSAM's extra data segment. For fixed-length records, 
blockfactor is the actual number of records in a block; for variable- 
length records, blockfactor is a multiplier used to compute block size 
from record size; ( (maximum recsize +1) * blockfactor) +1 = block- 
size. The value of blockfactor should be an integer that results in a 
block size less than 4K words. The blockfactor is from 1 through 255. 
If you specify a negative value or zero, the default value is used. Values 
greater than 255 are defaulted to the specified blockfactor modulo 256. 



numbuffers 



Default: 1 

integer by value (optional) 

An integer between 1 and 20 that specifies the number of key block 
buffers in the extra data segment used by KSAM files for buffering 
data and key blocks. The number of buffers is specified in bits 4-10; 
the rest of the word must be set to zeros: 



bits 



3 4 



10 11 



15 



Q V///////A Q 



i , 1 

number of buffers 

This number should only be specified if the default number assigned 
by KSAM affects performance. Refer to appendix B, under KSAM 
Extra Data Segments for a discussion of how the key block buffers 
are used. 

Default: Between 1 and 20 buffers depending on access type, 
number of keys, and number of levels per key. (Refer 
to appendix B.) 



filesize 



double by value (optional) 

A double-word integer specifying the maximum data file size as the 
number of logical records in the file. A zero or negative value results 
in the default filesize setting. The maximum file capacity is over two 
million (2%*-) sectors; a sector contains 128 words. 

Default: 1024 logical records 



MAY 1981 



4-43 



FOPEN 



numextents 



integer by value (optional) 

An integer specifying the number of extents (integral number of 
contiguously-located disc sectors) that can be dynamically allocated 
to the file as logical records are written to it. The number of extents 
applies equally to the data and key files on the assumption that there 
is a proportional expansion in each. The size of each extent is deter- 
mined by the filesize parameter value divided by the numextents 
parameter value. If specified, numextents must be an integer from 1 
to 32. A zero or negative value results in the default setting. 



Default: 8 extents. 



NOTE 



initialloc 



Extents are allocated on any disc in the device class specified 
in the device parameter when the file was created. If it is 
necessary to insure that all extents of a file are on a particular 
disc, a single disc device class or a logical device number must 
be used in the device parameter. 

integer by value (optional) 

An integer specifying the number of extents to be allocated to the 
data file when it is opened. (For a key file, this parameter is forced 
equal to the value of numextents. ) This must be an integer from 1 to 
32. If an attempt to allocate the requested disc space fails, the FOPEN 
intrinsic returns an error condition code to the calling program. 



filecode 



Default: 1 extent. 

integer by value (optional) 

An integer recorded in the file label and made available for general use 
to anyone accessing the file through the FGETTNFO intrinsic. This 
parameter is used for new data files only. The filecode applies to data 
files only; the key file code is always 1080 and need not be specified. 
For this parameter, any user can specify a non-negative integer. 

Default: 



CONDITION CODES 



CCE 
CCG 
CCL 



Request granted. The file is open. 

Not returned by this intrinsic. 

Request denied. This may be because another process already has 
exclusive or semi-exclusive access for this file, or an initial allocation 
of disc space cannot be made due to lack of disc space. The file num- 
ber value returned by FOPEN if the file is not opened successfully is 
zero. The FCHECK intrinsic should be called for more details. 
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FOPTIONS PARAMETER. 

Table 4-6. FOPEN f options Parameter Format 



BITS 

12 3 


4 


5 


6 


7 


8 9 


10 11 12 


13 


14 15 




KSAM 
FILE 


DIS- 
ALLOW 
:FILE 




CCTL 


RECORD 
FORMAT 


DEFAULT FILE 
DESIGNATOR 


ASCII/ 
BINARY 


DOMAIN 


Set shaded areas to zero for KSAM files. 


BITS 


OPTION 


SETTINGS 


14:2 


File Domain 


00 = New file created by FOPEN call. No search is required. The ksamparam 

parameter must be present to define the file structure, (default) 

01 = Old permanent file; search system file domain. 

10 = Old temporary file; search job file domain. 

1 1 = Old user file; search job file domain and, if not found, search system file 

domain. 


13:1 


ASCII/Binary 


= Binary code used to record data; any dummy records are padded wtih 

zeros, {default) 

1 = ASCII code used to record data; any dummy records are padded with 

blanks. 


10:3 


Default File 
Designator 


000 = Actual file designator is the same as the formal file designator, {default 
and only setting allowed for KSAM files. ) 


8:2 


Record Format 


00 = Fixed-length records, (default) 

01 = Variable-length records. (Other settings not allowed for KSAM files) 


7:1 


CCTL 


= Carriage control directive not expected, (default and only setting 
allowed for KSAM files. ) 


5:1 


Disallow :FILE 


= Allow :FILE command to override FOPEN file specifications. Note that 

forma/designator is the only :FILE specification allowed for KSAM 
files, (default) 

1 = Disallow (ignore) : FILE command file equations when in conflict with 

FOPEN. 


4:1 


KSAM 


= Not a new KSAM file, (default) 
1 = New KSAM file or exising KSAM file opened as an MPE file. 
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AOPTIONS PARAMETER. 



Table 4-7. FOPEN aoptions Parameter Format 



BITS 
1 



KSAM 
ACCESS 



NO 
WAIT 



8 



EXCLUSIVE 
ACCESS 



10 



DYN- 
AMIC 
LOCK 



11 



12 13 14 15 



ACCESS TYPE 



Set Shaded areas to zero for KSAM files. 



BITS 



12:4 



OPTION 



Access Type 



SETTINGS 



10:1 



Dynamic Locking 



0000 = Readonly, (default). Allows access to all intrinsics except: 

FWRITE,FUPDATE,and FREMOVE. 

0001 = Write only. Delete previously written data. Allows access to all 

intrinsics except: FREAD,FREADDIR,FREADC,FREADBYKEY, 
FUPDATE, FREMOVE, FSPACE,FPOINT,FFINDBYKEY, and 
FFINDN. 

0010 = Write only. Save previously written data. Allows access to same 

intrinsics as write only with delete. 

0011 = Same as above. 

0100 = Input/Output access. Allows access to all intrinsics except: FUPDATE 

and FREMOVE. 

0101 = Update access. Allows access to all intrinsics. 



8:2 



Exclusive Access 



= Disallow dynamic locking/unlocking, (default) 

* 1 = Allow dynamic locking/unlocking. Allows use of FLOCK and 

FUNLOCK intrinsics to permit or restrict concurrent access to file. 



00 = Default access depending on access type: if access type = 0000 (read 

only) default is 1 1 (share access); if access type is any other, default 
is 01 (exclusive access). 

01 = Exclusive access. Prohibits another FOPEN request to open the file 

until current process issues FCLOSE or terminates. 

10 = Semi-exclusive access. Allows another process to open this file for 
read only but prohibits any output access until this process issues 
FCLOSE or terminates. 

'11= Share access. After file is opened, permits concurrent access to the 
file by any process in any access mode, subject only to MPE security 
provisions in effect. 
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Table 4-7. FOPEN aoptions Parameter Format (continued) 



BITS 


OPTION 


SETTINGS 


4:1 


No Wait 


= No Wait input/output, (default and only setting allowed for KSAM 
files. ) 


3:1 


KSAM Access 


= KSAM access expected. 
1 = Non-KSAM access expected; KSAM key file or data file is treated as 

standard MPE file. For this setting to be meaningful, file must be a 

KSAM file (f options 4:1 = 1). 


* If dynamic locking is enabled with share access, a call to FLOCK must precede any call to FREMOVE, 
FUPDATE, or FWRITE. Note that a file equation that specifies shared access (FILE filename;SHR), 
automatically sets the dynamic locking option, forcing users to lock for all access. Also, if you specify 
SHR (aoptions. (8:2)), KSAM will automatically set lock bit (aoptions. (10:1)) which will require that 
the file be locked before issuing any intrinsics. 
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KEY FILE DEFINITION. The ksamparam array defines the key file for a new KSAM file. If the 
file has already been created, this parameter can be set to all zeros or omitted. Otherwise, it must 
be assigned values to define the key file as shown in table 4-8. 



When a new KSAM file is created, the MPE end-of-file for the key file is set to the file limit. The 
file limit is based on the key file size (see words 4-5 of ksamparam). The location of the key file 
end-of-file can be determined by executing the VERIFY command of KSAMUTIL and looking 
at the heading KEY FILE EOF. A call to FGETKEYINFO returns the key file size as the number 
of sectors used by the file. 









Table 4-8 


FOPEN ksamparam Parameter Format 




1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

80 


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 


\ 

/ 
\ 

/ 

\ 

/ 
\ 


Basic Key File 
Definition 
(17 words) 

Primary Key 
- Definition 
(4 words) 

1st Alternate 
Key Definition 
(4 words) 

Up to 14 More 
Alternate Key 
Definitions 
(16 keys total) 


Key File Name 
(8 bytes) 


Key File Size (maximum number of primary keys) 
(double word) 


Key Device 
(8 bytes) 


(reserved) 


Flagword (1 


word) 


Number of Keys (1 byte) 


Key Type Key Length 


Key Location 


D 


Minimum (Maximum) Number of Keys Per Block 


(reserved) 


R 


(reserved) 


Key Type 


Key Length 


Key Location 


D 


Minimum (Maximum) Number of Keys Per Block 


(reserved) 


R 


(reserved) 


^ 
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This array defines the key file portion of a new KSAM file being created by the FOPEN call. The 
values are: 



Key File Name 



Key File Size 



Key Device 



8-byte file name that must be present if this is a new file. Only the 
name is specified; the account, group, and security are taken from the 
data file formal file designator. 

Double-word specifying the maximum number of primary keys expected 
from which the key file size is derived. If zero, the data file size is used. 

(Note that a call to FGETKEYINFO returns the key file size as the 
number of sectors in the file.) 

8-byte array that specifies the device on which the key file resides. 
Specified as a device class name of 1-8 alphanumeric characters begin- 
ning with a letter and terminated by a non-alphanumeric character such 
as a blank; or it is specified as a logical device number (3-byte numeric 
string) identifying a particular device. If the data file is assigned to a 
remote device the key file is automatically allocated to the same 
machine. Default is DISC. 



Flagword 



1-word that specifies file characteristics as shown below: 






0123456789 10 11 12 


13 


14 


15 


reserved 


SW 


RN 


JT 



JT 



RN 



( bi 



SW - 



bit 15:1 = 1 if file is job temporary file 

= if file is a permanent file (default) 
14:1 = 1 if record numbering starts with 1. 

if record numbering starts with 0. (default) 
13:1 = 1 if only sequential writing by primary key value is 
allowed. 
= if random writing by primary key value is allowed. 
(default) 
0:13 = all reserved bits must be set to 0. 



Number of Keys 
Key Definitions 



bits 



1 byte providing the total number of keys for the file, specified as a 
numeric digit between 1 and 16. (left byte of word should be zero). 

Each key in the file requires a 4-word definition. The first definition 
is always of the primary key. Subsequent definitions describe any 
alternate keys. Up to 15 alternate keys are allowed in any one key file. 
The key definitions each contain the following information: 






12 3 


4 5 6 7 


8 9 10 11 12 13 14 


15 


Key Type 


Key Length 


Key Location 


D 


Minimum (Maximum) Number of Keys per Block 


(reserved) 


R 


(reserved) 



4-48 



FOPEN 



Key Type 



Key Length 
Key Location 

D (Duplicate Flag) 



Minimum (Maximum) 
Number of Keys per 
Block 



The information for each key has the form shown above starting in 
word 17 of ksamparam. It is defined as follows: 

4 bits specifying the type of the key by the following code: 



bits 0:4 



0001 (1) 

0010 (2) 

0011 (3) 

0100 (4) 

0101 (5) 
0110 (6) 
0111 



(7) = 



1000 (8) 



Byte key (1 to 255 bytes) 

Integer key (2 bytes) 

Double Integer key (4 bytes) 

Real key (4 bytes) 

Long key (8 bytes) 

Numeric Display key (1 to 28 bytes) 

Packed Decimal key, odd number of digits 

(1 to 14 bytes) 

Packed Decimal key, even number of digits 

(2 to 14 bytes) 



Refer to figure 2-2 in section II for a full description of key type. 

12 bits specifying length of the key in bytes. Length is a function of 
key type (see key type) but must never exceed 255 bytes. 

1 word specifying the location of the first byte of the key in the record. 
Bytes in a record are numbered starting with 1. (Note that it is good 
practice to leave the first two bytes of a record empty of keys since 
these bytes are used by FREMOVE for the record delete code.) 

1 bit that determines if duplicate values are allowed for this key: 
= if duplicate key values are not allowed (default) 
= 1 if duplicate key values are allowed. 

15 bits that specify the minimum number of keys allowed per key 
block. The value must be an even-numbered integer greater than or 
equal to 4. If the resulting key block size is greater than 2048 words, 
this number may be reduced automatically. In order to make optimum 
use of disc space, KSAM may increase the value specified here. If KSAM 
increases the number of keys per block, this new value is the maximum 
size of the key block. (Refer to appendix B for particulars on the cal- 
culation of block size and the adjustment of the blocking factor.) The 
default generates a block size of IK (1 024) words. 



R (Random Insert Flag) 



1 bit (8:1) that determines whether duplicate key is to be inserted ran- 
domly in duplicate key chain or is to be added to the end of the chain; 
the duplicate flag (D bit) must be set to 1 in order to use this flag. 



= 



= 1 



if duplicate key values are to be inserted at the end of the 
chain (default) 

if duplicate key values are to be inserted randomly. If inserted 
randomly, the chronological order of duplicate keys is no 
longer maintained, but the addition of keys is faster. 
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OPENING A NEW FILE 

When FOPEN is used to open a new KSAM file, you must provide all the information needed to 
create the two files that make up a KSAM file: the key file and the data file. To inform the system 
that this is a KSAM file, the KSAM bit must be set in the foptions parameter; and the ksamparam 
parameter must be included to define the key file. 

Figure 4-5 is a short SPL program that builds a KSAM file. The file has two keys; the primary key 
starting in column 1 is 20 characters long, and the alternate key starting in column 21 is 8 charac- 
ters long. The primary key will contain a name, the alternate a phone number. 

The first step is to declare all arrays and variables needed by the program followed by the intrinsic 
declaration for FOPEN. The shaded declarations in figure 4-5 show these required to open the 
file; others are used in parts of the program not shown in this figure. 

The next step is to move the necessary values to ksamparam in order to define the key file. 

The last step is to call the FOPEN intrinsic, passing any previously defined variables or arrays by 
reference and passing all others by value. 

DECLARATIONS FOR FOPEN. The array ksamparam is defined three different ways: as a 
numeric array containing 25 words (KSAMPARAMA), as a byte array equivalenced to the numeric 
array (KSAMPARAM), and as a double array also equivalenced to the numeric array (KSAMPARAMD). 
These three definitions allow the array to be addressed by word, by byte, or by double word as required. 

The variable to which the file number is returned is declared to be an integer. 

The two arrays that will contain the formal designator and device parameter values are declared 
and assigned these values. In this case, the formal designator is assigned the value JEXAMFIL. 
This name identifies both the KSAM file in its entirety and the data file if referenced separately. 
The device class name assigned to the device parameter is DISC. 

Finally, the intrinsic itself is declared in an INTRINSIC statement. 

DEFINING KSAMPARAM. The ksamparam parameter is assigned a variety of values that, for the 
sake of clarity, are assigned in separate statements. The values assigned to ksamparam define the 
key file. The statements that move values to ksamparam (refer to figure 4-5) tell the system every- 
thing it needs to know in order to build the key file. 

The first item moved to ksamparam is the key file name, up to 8 characters enclosed in quotes. In 
this case, the key file name is JKEYFILE. 

Next, the size of the key file is defined in terms of the maximum number of primary keys expected. 
The size is specified as a double word integer and is assigned to the third double word in the array, 
specified by an index of 2 counting from double word 0. The maximum number of primary keys 
should be the same as the maximum number of records specified in the filesize parameter of 
FOPEN. KSAM assigns a key file size based on this value. If there are alternate keys, the key file 
size is made proportionately larger. If the key file size is specified as zero, KSAM uses the value 
of the FOPEN filesize parameter as the key file size. 

The device class name is assigned in the 8 bytes starting in byte 12 that are allocated to device 
description. In this case, the device class name is DISC, the same as the device class name specified 
in the device parameter of FOPEN for the data file. 
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SCONTPOL MAlNsjEXAMPLl 

<<» *>> 

<<# EXAMPLE 1 •>> 

<<» BUILD A *SAM FILE »>> 

<<# »>> 

«t«»t«»»»l«0»««»««»<**«««««««<l««ft««»«t»t«««»lt<>«*»(t#«tt» 

AR - : ■ '■ S-^'-A ■ .'.--"■ ( i ; ; ; 

9YTE SBRfi ^SAMPflSAf »■•:.'■;■..,••.>:.•.--! 

D ■■.■„■■.-:■■--•■ K S AMPa« AMD I • J »KS A MP AbA-^6 | 

imf_3j;r filnumi 

I\»E3EH fcRRCRCOOE) 

HTE3FR LF.WH| 

a '-'. ARPftv F \-\-"<: ■ :• i -'; : s JtXftt-FIL -i 

Byte iS??Ar OEV ICE I I VJ J =»DISC 

ARRAY- MESSAGE (0U5) t 

ARRAY INPUT (0«39) I 

ARRAV OUTPUT (*) alNPUTl 

IM-GIN.9TC F-OPeN«FCLOSEi^WHlTE,READ,PRINT,TERMINATEI 

INTRINSIC FtHEC«,FERRMSu| 

<<# SETUP KSAMPARAM FOH FOPEn «>> 
<<*#»»»»#»*«»»»«*«*««»***»o«»»e*»>> 

MOVE KSAMPAHAMr«"JKEYFlLE»| <<TH£ KEY FILE SAMt>> 

KSAM3ARAMD(2) J«l0OO| <<TH£ MAX, « OF PRIMARY KEYS>> 

MCVE KSAMPA«AM<12J |«i>OISC»J <<THE KEY FILE OEVlCE TYPE>> 

KSA"»ARAMA(1S) t«fc(2) 0000000000000 1 K<TME FLAG WORD>> 
KSAM»ARAM(l3> »»2| <<P«IMARY KEY i. ONE ALTERNAT£>> 

MOVE teSAHPAHAMA(I'TMptt<»/l l 12/201 ( '«T.V^e*ASCIII LEN©Th«2o BYT€S>> 

I > <<KEY LOCATION START F&pM COL 1>> 

u/o,l3/«j ,<<oup >,,:■ allow j - <*■■■ -::-_?.;*>> 

01 I «hESER«/ED» ' 

MOVE KSAMPARAMA(Sl) i»(I < »/lil2/e3t<<TYPE«ASCIII LEN6Th»2o BYTES>> 

21 » <«KE> LOCATION STA*7 *..C" COL ?l>> 

CI/0,lS/<4j, <<DUP MOT ALLOW) 4 K£Y/BLOCK>> 
' ■■ * «<HES£H «'f.;" .* > 

<<» open the ksam file •>> 

filnjm:«foben«fILname, <<the oata file name>> 

*<2iOOO«10000000O10O»«KSAMiASCII,M£W FILE>> 
%12J0O^00O<JOOl00O00l,<<KSAM ACCESg^EXCLUSI VE , W«ITC>> 
-7a, «HECORC ';-' BYTES LONG>> 

DEVICE! <<DEVICE*OISC>> 

^SAMPARAMf «THIS DESCRIBES THE KEYS>> 



THEN BEGIN <<CANNOT OPEN 

MOVE MESSAGE j stiCANNOT OPEN 
PRINT(MESSAQE,-21,0) ) 

FCHECK(FILNUM,ERRORCODE) ) 
FERR MS >G (ERRORCODt.MESSAGE.I 
PRINT (MESSAGE, -LtNGTH r O) ) 
TERMINATE) 
END! 



<<fi»K0UFFER$ MOT USED 

? ;<*f-w& ;f rye c*jf -.hou> • 


>> 

loo 


RECO»0» 


KSAM FILE>> 
KSAM FILE") 








.ENGTH) | 


<<QET THE ERROR NUMBER>> 
<<QET MESSAGE STRING>> 
<<PRINT ERROR MESSAGE>> 



Figure 4-5. FOPEN Example — Building a KSAM file 
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Word 15, the flag word, is set next. It uses bits 13, 14, and 15 to define three conditions of the 
key file. In this example, bit 14 is the only bit set. This means that record numbers in the file start 
with 1 rather than (bit 14=1), that the file is a permanent file saved in the system directory (bit 
13=0), and that records may be written to the file in random order rather than being restricted to 
ascending sequence by primary key (bit 15=0). In figure 4-5 the flag word is specified as a binary 
value for clarity; it could have been specified as octal 2 (2 or %2) for brevity. 

The right byte of the 16th word (byte 33) is set to 2 to specify that two keys are to be used: the 
primary key and one alternate. 

This completes the general description of the file. Its name, size, device type, special conditions, 
and number of keys are now specified. The remainder of ksamparam defines each key in 4-word 
entries. The first entry always describes the primary key. Subsequent entries define up to 15 
alternate keys. In this case, one primary and one alternate are defined. 

Starting in word 17, the primary key is defined as type ASCII, 20 bytes long, its location starting 
in the first character of each record, and duplicate values are not allowed. It is blocked with four 
keys per block. 

Starting in word 21, the alternate key is defined as type ASCII, 8 bytes long, located starting in 
character 21 of the record, duplicate values not allowed, and blocked four keys per block. 

Refer to table 4-8 for an illustration of the bit patterns used to define the ksamparam entries. 

CALLING FOPEN. When all the variables and arrays that pass values by reference have been de- 
fined, the intrinsic FOPEN can be called. In figure 4-5, each parameter is shown on a separate line 
and documented for clarity, but the call could also be specified as: 

FILNUM:=FOPEN(FILNAME,%4004,%10101,-72,DEVICE,KSAMPARAM,,10,0,100D); 

This call is identical to the call in figure 4-5 except that octal values are used for foption and 
aoption. 

f options 

The value of f options is set to octal 4004, for which the bit pattern is: 

Bits 

Binary 

Octal 
This specification defines the following file options: 

New KSAM file (bit 4=1) 
Allow :FILE (bit 5=0) 
Fixed-Length Records (bits 8,9=00) 
ASCII code (bit 13=1) 
New file (bits 14,15=00) 

aoptions 

The value of aoptions is set to octal 101, for which the bit pattern is: 






1 


2 3 


4 


5 6 


7 


8 9 


10 


11 


12 


13 


14 


15 











1 




















1 


















4 
















4 









2 3 







4 5 6 







7 8 9 



1 



10 11 12 







13 14 15 







Bits 

Binary 

Octal 



4-52 



FOPEN 



This specification defines the following access options: 

KSAM access expected (bit 3=0) 
Exclusive access (bits 8,9=01) 
Dynamic locking not allowed (bit 10=0) 
Access type is write only (bits 12-15=0001) 

OPENING AN EXISTING FILE 

Once the file has been created, opening it again after it has been closed is a simple process. The 
record size, device, blocking, buffersize, and file size are all defined for the data file. Therefore 
these parameters need not be repeated. The key file has already been defined so that ksamparam 
need not be specified. This leaves the first three parameters to specify. Of these, only the formal 
designator and the domain option of the f options parameter are always required. The formal- 
designator provides the file name in order to identify the file. The domain option specifies where 
to locate the file; if domain is set to zeros, the system expects a new file. If the file is to be read 
only, the access mode parameter, aoptions, can be omitted. For any other type of access, aoptions 
should be specified. 

OPENING FILE FOR READ ACCESS. The example in figure 4-6 illustrates opening a file for read- 
only access. 



^CONTROL MAIN»JEXAMP|_2 

<<» •» 

<<» «>> 

INTEGER ^ILNU*} 
INTEGER efc^QSVQjSOtENS^Hf 

*Y7£ APRAy » , "It.MAMs:l0<OM* , 'JeXAMFlU "I 
AKRAV MESSAGf (0 M5> » 

ARRAY 1NPUT(0:39) | 

ARRAY OUTPUT(»)*INPUT| 

BYTE ABRAY *E YvA^UE ( : 7 ) 8 s"000-0000" I 
INTEGER KEYLENQTHlrfll 
INTEGER KEYL0CATI0NI=21» 
INTEGER "EL0P«»3I 

If*T*i*,SIC F0Pc.N,rCL0SE,FREA0,FFlND8YKEY,READ,PRlNT, 
FCHtCK, FERRMSG #PRI NT 'FILE'INPO, TERMINATE I 

<<» OPEN THE KSAM flLF *>> 

FiLNUM|«F0PEN(FH.NAMF,3U <<0PEN THE KSAM FU.E>> 

IF FlLNUMsO 

THEN BEGIN <<CanN0T OPEN KSAM FlL£>> 

MOVE MESSaGeJ»"CannOT OPEN KSAM FIl-E"l 

PRINT(MESSASEi-2li0> » 

fcheckifilnum.eprorcodej i <<get the error numbcr>> 

ferrmsg(errorcode|message, length) i <<get message strlng>> 

prinhmessage, -length, o> i <<print error messaoe>> 
terminate! 

END| 



Figure 4-6. FOPEN Example — Opening an Existing File 



4-53 



FOPEN 



The file name is specified in the FILNAME array declaration as JEXAMFIL. This is the file that 
was created and opened for write-only access in figure 4-5. It is opened for read-only access with 
the call: 

FILNUM:=FOPEN(FILNAME,3); 

The value of f options is set to the value 3, for which the bit pattern is: 

Bits 

Binary 

Octal 
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2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 
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1 


1 



































3 





This specification defines the following file options: 

Not a new KSAM file (bit 4=0) 
Old user file (bits 14-15=11) 

Because this is an existing (old) user file, other f options settings defined when the file was created 
need not be respecified. For example, at creation the file was defined as containing ASCII code 
(bit 13=1). In subsequent FOPEN calls this bit can be without changing the code to binary. 

When an old user file is opened, the job file domain is searched first and then the system file domain 
is searched for the file specified in the formal designator. 

The access parameter, aoptions, is not specified, but by default it specifies the following access 
mode: 

KSAM access expected 

Share access (default for read-only) 

Read-only access 

OPENING FILE FOR WRITE ACCESS. To open an existing file for write access, you use the same 
foptions values as you do to open the file for read-only access. The different access mode is speci- 
fied in the aoptions parameter. 

For example, assuming FILNUM and FILNAME have been declared: 
FILNUM:=FOPEN(FILNAME,3,l) 

The foptions specification is the same as described above. The aoptions specification is: 

Bits 
Binary 
Octal 
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This bit pattern defines the following access options: 

KSAM access expected (bit 3=0) 

Exclusive access (default for all access modes except read-only) (bits 8-9=00) 

Disallow dynamic locking (bit 10=0) 

Write only access (bits 12-15=0001) 

This opens the file for write-only access in which all previous data is deleted. It is the access mode 
to use when writing to a file for the first time. If you want to write to the end of an existing file 
then bits 12-15 should equal 0010 and aoptions could be specified as 2 if other aoptions values are 
defaulted. To open the file for both reading and writing, bits 12-15 should be set to 0100, or the 
value 4. For update, these bits are set to 0101, or the value 5. 

OPENING KSAM FILE AS MPE FILE. You may want to open either the key file or the data file 
as a standard MPE file. To do this, name the file you want to open in the formaldesignator param- 
eter, set foptions bit 4:1 to 1, and then set aoptions bit 3:1 to 1. These settings indicate that the 
file is a KSAM file, but is to be treated as an MPE file. The remaining parameter settings depend 
on what you want to do with the open file. For example, if you want to read the key file, 
JKEYFILE, as an MPE file, you call FOPEN as follows: 

INTEGER FILNUM; 

BYTE ARRAY FILNAME(0:9):="JKEYFILE "; 



INTRINSIC FOPEN, . . . ; 

FILNUM:=FOPEN(FILNAME,%4003,%10000); 

The value of foptions defines the following file options: 

Specified as KSAM file (bit 4=1) 
Old user file (bits 14-15=11) 

The value of aoptions indicates the following: 

Non-KSAM access expected (bit 3=1) 

Share access (default for read only bits 8-9=00) 

Read-only access (default bits 12-15=0000) 

Normally, the only time you need to set bit 4 of foptions to 1 is when you are originally creating 
a KSAM file. However, when you are opening an existing KSAM file for non-KSAM access, you 
must set this bit to 1 so that the system can distinguish the KSAM data or key file from an MPE 
file. 
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OPENING FILE FOR SHARED ACCESS. When a file is opened for shared access (aoptions bits 
8,9 = 11), and you plan to modify the file in any way, you must enable dynamic locking (aoptions 
bit 10 = 1). This is necessary since you cannot call FWRITE, FUPDATE, or FREMOVE to modify a 
shared file without first calling FLOCK to lock the file. 

Even if you are not planning to modify the file, but only plan to read it sequentially, you should 
allow dynamic locking when you open the file. This is because FREAD (as well as FUPDATE and 
FREMOVE) is a pointer-dependent procedure. Any time you call a pointer-dependent procedure 
(refer to table 4-2), you must precede it with a call to a pointer-independent procedure that posi- 
tions the pointer. It is important to call FLOCK to lock the file before setting the pointer with the 
pointer-independent procedure and leave it locked until you have completed the sequential read or 
update. This insures that no other user changes the position of the pointer between the call that 
positions the pointer and the call that depends on the pointer. 
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INTRINSIC NUMBER 6 
Sets the chronological (and logical) record pointer for a KSAM file. 



IV DV 
FPOlNT(filenum,recnum); 



The FPOINT intrinsic sets the chronological record pointer for a KSAM disc file. The file may con- 
tain either fixed-length or variable-length records. When the next FREADC request is issued for 
this file, the record to which FPOINT positioned the pointer is read. Note that this intrinsic posi- 
tions the logical record pointer as well as the chronological pointer. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file on which the 
pointer is to be set. 

recnum double by value (required) 

A positive double integer representing the record number of a fixed- 
length file or the word pointer to a variable-length file. Word number- 
ing always starts with word 0, whereas record numbering starts with 
or 1 depending on how the file was created. In either case, the number 
is in terms of the chronological (consecutive) order in which the data 
file records were written. It has no relation to the logical record pointer 
that is based on key values. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied. The chronological record pointer position is un- 

changed. Positioning was requested at a point beyond the physical 
end-of-file. 

CCL Request denied. The chronological record pointer position is un- 

changed because of one of the following: 

Invalid filenum parameter. 

recnum parameter specified a record marked for deletion. 

A key value for specified record not found in key file. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 
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USING FPOINT 

The FPOINT intrinsic is generally used prior to an FREADC intrinsic in order to read a record 
without reference to the key file. FPOINT sets the chronological record pointer to the position in 
the file specified by recnum. A subsequent FREADC reads the record (or portion of a record) to 
which the pointer is positioned. It then sets the pointer to the next record that was written to the 
file in chronological order. 

For example, in order to read the 39th record written to the file identified by FILENUM: 

FPOINT(FILNUM,39D); - set pointer 

FREADC(FILNUM,BUFFER,COUNT); - read record 

Following execution of FREADC, the contents of the 39th record are transferred to the array 
BUFFER and the chronological pointer remains positioned at record 39. A flag is set so that the 
next call to FREADC moves the pointer forward to the beginning of record 40, the next record 
in chronological order. 

Note that the combination of FPOINT followed by an FREADC intrinsic is identical in effect to 
the FREADDIR intrinsic that positions to a chronological record number and then reads that 
record. The FGETINFO intrinsic can be used to recover the chronological record number of the 
record most recently accessed. (Refer to FGETINFO and FREADDIR for more information on 
accessing records by chronological record number.) 

Since the FPOINT intrinsic positions the logical pointer as well as the chronological pointer, it can 
be used prior to an FUPDATE or FREAD intrinsic to identify the record to be updated or read. 
FPOINT sets the logical record pointer to a key in the key file that points to the record it located 
by record number. The key is by default the primary key for that record, though an alternate key 
is used if such a key was selected by a prior call to FFINDBYKEY or FREADBYKEY. 

SHARED ACCESS. When you use FPOINT to position the chronological pointer in a shared access 
environment, you must lock the file with a call to FLOCK before calling FPOINT. You should 
leave the file locked until you have completed any calls that read or update the file in chronological 
sequence, and then call FUNLOCK to unlock the file for the other users. This insures that the 
pointer is not moved by other users between the pointer-independent procedure FPOINT and any 
subsequent pointer-dependent procedure. (Refer to table 4-2 for a list of the pointer-independent 
and pointer-dependent procedures.) 
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INTRINSIC NUMBER 2 
Reads a logical record in key sequence from a KSAM file to the user's stack. 

I IV LA IV 

lgth:=FREAD(filenum, target, tcount); 

FREAD reads a logical record in sequential order by key value. The primary key determines key 
sequence unless a prior call to FFINDN (or FFINDBYKEY or FREADBYKEY) has specified an 
alternate key. If the file is opened without KSAM access (FOPEN aoptions bit 3=1), then FREAD 
reads the data file as if it were not a KSAM file. 

The record read by FREAD depends on the current position of the logical record pointer. 



FUNCTIONAL RETURN 

The FREAD intrinsic returns a positive integer value to Igth showing the length of the information 
transferred. If the tcount parameter in the FREAD call is positive, the positive value returned 
represents a word count; if the tcount parameter is negative, the positive value returned represents 
a byte count. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be read. 

target logical array (required) 

An array to which the record is to be transferred. This array should 
be large enough to hold all of the information to be transferred. 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be transferred. 
If this value is positive, it signifies the length in words; if it is negative, 
it signifies the length in bytes; if it is zero, no transfer occurs. 

If tcount is less than the size of the record, only the first tcount words 
or bytes are read from the record. If tcount is larger than the size of 
the physical record, transfer is limited to the length of the physical 
record. 

CONDITION CODES 

CCE The information was read. 

CCG The logical end-of-data was encountered during reading. 

CCL The information was not read because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 
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USING FREAD 

The FREAD intrinsic reads the record at which the logical record pointer is currently positioned. 
When a file is opened, this pointer is positioned to the beginning of the first record in primary key 
sequence. That is, it is positioned to the record containing the lowest value in those bytes con- 
taining the primary key. 

Following each FREAD , the record pointer remains positioned at the record just read. Any sub- 
sequent FREAD call positions the pointer to the next sequential record in ascending key sequence. 
Also, if an FREAD call is followed by an FUPDATE and another FREAD, the pointer is advanced 
before the second FREAD. 

A key other than the primary key can be selected as the basis of the sequential read by executing 
FFINDN, FFINDBYKEY, or FREADBYKEY before executing the FREAD intrinsic. 

When the logical end-of-data is encountered during reading, the CCG condition code is returned to 
your process. The end-of-data occurs when the last logical record of the file is passed . Note that the 
last logical record of a KSAM file is the record containing the maximum key value in the key on 
which the key sequence is based. 

SHARED ACCESS. In order to be sure that you are reading the record you want, you should call 
either FLOCK or FCONTROL with control code 7 before calling FREAD. FLOCK prevents other 
users from changing or deleting the record until the file is unlocked with FUNLOCK. FCONTROL 
with control code 7 clears the data and key block buffers so that the record must be read directly 
from the file, and also transfers the latest control information from the file to the extra data seg- 
ment. Because the logical pointer is part of this control information, you can be sure that is is set 
correctly by calling FCONTROL with code 7. 

FCONTROL uses less overhead than FLOCK, but it cannot prevent other users from modifying the 
record you want to read while you are calling FCONTROL. FLOCK, on the other hand, fully pro- 
tects the information to be read from changes by other users but requires more time. 

Because FREAD is a pointer-dependent procedure, you must call one of the procedures that posi- 
tion the pointer before calling FREAD. When you are reading the file in sequential key order, it is 
important to lock the file before calling the procedure that positions the pointer, and to leave it 
locked while you are reading the file. This insures that the pointer is not moved by another user 
between the call that positions the pointer and FREAD or between sequential FREAD calls. (Refer 
to table 4-2 for a list of the pointer-independent and pointer-dependent procedures.) 

For example, the following sequence of calls guarantees that you will read the file in sequential order 
starting with a specified key : 

FLOCK 

FFINDBYKEY- sets logical pointer 

FREAD loop -« read records in key sequence 

FUNLOCK 
Note that FREAD advances the record pointer only if it is followed by another FREAD (or an 
FUPDATE followed by another FREAD). A single call to FREAD leaves the pointer at the record 
just read; a subsequent call to FREAD causes the pointer to be positioned to the next record in key 
sequence. This permits sequential reading of the file without calling a pointer-independent proce- 
dure before each FREAD. Also, in order to allow sequential updates, the pointer is advanced for 
each FREAD in an FUPDATE/FREAD sequence with no other intervening calls (see FUPDATE 
discussion) . 

In the example in figure 4-7, FREAD is used first to read the KSAM file in sequence by primary 
key. When the end of data is reached, the program uses FFINDBYKEY to specify an alternate 
key and FREAD then reads the file in sequence by that alternate key. When the end of data is 
reached again, the file is closed. (Note that this program is opened for exclusive access so that 
locking is not necessary). 
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SCONTROL MAIN»JEXAMPL2 

»>> 

EXAMPLE 2 *>* 

READ A KSAM FILE SEQUENTIALLY »>> 



<<* 



«GET THE ERROR NUMBER>> 
«5ET MESSAGE STRING>> 
<<PRINT ERROR MESSAGE>> 



<<* 

jwtesga riLNUHi 

I»*TEG£R £RRO«CCO£,l»ehKSTH* 

BVTt arrav riWf**M£iDJ9>»*«<aExAMriL "I 

ARRAY MESSAGEI0I35) I 

ARRAY INPUT10J39) I 

ARRAY OUTPUT (•> *INPUT1 

SYTE 4SR&V «Eyv'AU^El'0STM»»000«000ff**t 

iNTtecKj KE^ue-seTHtasaj 

iNTEOES K£YuOCAr!ONt*i-t I 

INTHINSIC FOPEN.FCLOSE.FREAD.FF-lNOBYKEY.REftn.PRINT, 
FCHECK.FERRMSG, PRINT 'FILE'InFO, TERMINATE! 

<<* OPEN THE KSAM FILE ♦>> 

FILENUM:=FOPEN(FILNAME,3,200); <<OPEN KSAM FILE FOP EXCLUSIVE READ-ONLY ACCESS>> 

IF FILNUMaO 

THEN BEGIN <<CANNOT OPEN KSAM FILE>> 

MOVE MESSAGE;s"CANNOT OPEN KSAM FILE" I 

PRlNT<MESSAGE,-2li 0) » 

FCHECK(FlLNUM,ERRORCODE) » 

FERRMSGlERRORCODE, MESS AGE, LENGTH) I 

PRINTfMESSAGE, -LENGTH, 0) » 

TERMINATEl 
END | 
MOVE MESSaGE«»"LIST IN LAST NAME SEQUENCE"! 
PRINT(MESSAGE,-26,0) I 

<<» READ KSAM IN NAME SEQUENCE *>> 

FRErtD(FlLNUM,INPUT,-72) I <<REA SEQUENTIALLY BY PRIMARY K E Y» 

THEN GO To L2| « G ° T0 ALTERNATE KEY ORDER>> 

IF < 

THEN BEGIN 

MOVE MESSAGE I «"ERROR OCCURRED WHILE READING INPUT'«| 

PrINT(MESSAGE,-34|0> I 

TERMINATEl 
ENO| 

<<• WRITE THE DATA JUST READ FROM KSAM FILE •» 

PRINT{OUTpUT,-T2,0) I 

<<• GO BACK TO GET ANOTHER RECORD •>> 

GO TO Lll 



Figure 4-7. FREAD Example 
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<<• HEAD DATA FROM KSAM FILE IN TEuEPHOMF * SEQUENCE •>> 

L2I 

FFINDByKE Y (FIlNUM,KEYvALUE,KEYLOCATION,KEYLFNGTH,RElOP> » 
MOVt MESSfts3EJ*"t.IST l» T£LE*><-*»NS 'O. gravS-oiCE" J 
PHI'-' iHtSSAGF ,-30,01 I 

='C3> •"•'., .\ : ; ' , ; -"•' ' : t „• ' : '" , :'; •' ; '.; ;■ '■ •■ - ., .- . ■•'.', ^ ■'< ■■'.",■', - ; "- * : rj" ■■■'■.' ; ; ; . : ' ■ • '•'■ ". ; ;• • ■<'■ ",:, ; ■ 

* r * 

THEN BEGIN <<ENq OF FILE>> 

FCtOSE(FIUNUM,0,0) I <<CLOSE ThE KSAM FILE>> 
IF <> THEN 

BEGIN <<CU0SE UNSUCCESSFUL>> 

"OVE MESSAGE»»"CANNOT CLOSE THE KSAM FILE"! 
PRINT(MESSAGE t -S9,0) I 

FCHECK(FILNUM,ERRORCODE) J <<GET THE ERROR NUMBER>> 

FFRPMSGIERRORCODE, MESSAGE, LENGTH) I «GET MESSAGE STRING>> 
PRINT(MESSaGE ( -LENGTh,0) I <<PRINT ERROR MESSAGE>> 

ENOI 
TERMINATE! 
END) 
IF < 

then begin 

move messagej»"error occurred while reading input"! 

PRINT<MESSAGE,-3«iO) | 
TERMINaTEI 

END| 

<<»***««««««««ttO««««0»«««««*««*«*«»»«»»»««»«*»» a «> > 

<<» WRITE THE DATA JUST READ FROM KSAM FILE »>> 

<<»»»»*oo»Stt««»»»»e»»«o»»»»»tn»»Ht»«» # » tt » < i» #))( , (tei , e » >> 

PRINT(OUTPUT,,72,0) » 
IF <> 

then begin <<error occurred while printing 0utput>> 
move m e ssage !«»error occurred while printing output»i 
print (mess age, -36, o> i 

FCHECK(FILNUM,ERR0RC0DE) » <<GET THE ERROR NUm B ER» 

FERRmSg(ERRORCODE,MESSAGE,LENGTH) |<<GET MESSAGE stRIng>> 
PRINT (MESSAGE, -LENGTH, 0) I <<PRINT ERROR MESSaGE>> 

TERMINATE! 
END! 

<<« go Back to get another record •>> 

GO TO L31 
END I 

Output from Program Execution: 



List in 


LAST NAME 


SEQUENCE 


Ca-join 


SICK 


578-7018 


ECKSTEIN 


LEO 


287-S1J7 


HCS05A 


JOE 


227-B214 


NClI'J 


JACK 


923-4975 


PflSOV 


LINDA 


:■»■-.■ 3 i 


RcaER T 


TERRY 


259-5535 


Sfelv 


HENRY 


293-4220 


TURNEWR 


I YA.\ 


984-8498 


WfsTfR 


ELOER 


287-4598 


white 


GORDON 


398-0301 


LIST IN 


TELEPHONE 


NO. StQUENCE 


HosntJA 


JOE 


227-8214 


Rc-iE'T 


GERRY 


259-5535 


west;r 


ELDER 


287-4598 


ECKSTFIN 


LEO 


287-5137 


se ■ . ■ 


ht'NHY 


293-<, 22 o 


p»sby 


LINDA 


29&-1187 


WHI T£ 


GORDON 


398-0301 


carcin 


■ : . ■ 


5*8-7018 


NCLAVJ 


JACK 


923-4975 


TijRNFWR 


IVAN 


984-8498 



' 1 1 100 WOLFE ROAD 
53"3 STEVENS CREEK 
11«<1 SAINT PETER CT, 

--=■" ■■-.■: AVE, 

T 0«N .<. CMTBY VILLAGE 
12345 TELEGRAPH A V E. 
11<>4 LEBERTY ST. 
22905 EMERSON ST, 
1?56 KINGFISHER ST, 
435o ASHBY AVE, 

llPn SAINT PETER CT, 
12345 TELEGRAPH AvE, 
125ft KINGFISHER ST, 
5303 STEVENS CREEK 
11*4 LEBERTY ST. 
TOWN & CNTRY VILLAGE 
4350 ASH9Y AVE, 
lllOO WOLFE ROAD 
967 REEO AVE, 
?2<»0S EMERSON ST. 



Cupertino 


ca. 


94053 


S AN T A ; ■_ A -■- ■■ 


CA. 


95050 


■ OS 6 L T S 


CA. 


9402? 


SUNNYVALE 


CA. 


94087 


San josE 


CA. 


94102 


BERKELEY 


:a. 


90871 


EL CERRITO 


CA. 


94053 


OAKLAND 


CA. 


98234 


SUNNYVALE 


CA. 


43098 


BERKELEY 


CA. 


91234 


LOS ALTOS 


CA. 


94022 


b ERK£LEY 


CA, 


90871 


Sunnyvale 


'-. 


43098 


Santa clara 


CA, 


95050 


EL CERPITO 


CA, 


94053 


S «N JOSE 


CA. 


94102 


BERKELEY 


CA. 


91234 


Cupertino 


CA, 


94053 


Sunnyvale 


CA. 


940B7 


Oakland 


CA. 


98234 



END OF PROGRAM 



Figure 4-7. FREAD Example (continued) 
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INTRINSIC NUMBER 304 



Reads a logical record randomly from a KSAM file to the user's data stack. 

I IV LA IV B.\ IV 

lgtk:=FREADBYKEY(filenumJarget.tcount,keyvalue,keylocation); 



FREADBYKEY reads a logical record selected by key value. The record to be read must have the 
same value as keyvalue in the bytes that start at keylocation. Following execution, the logical 
record pointer is still positioned to the record in the file located through the value of the key at 
keylocation. 

FUNCTIONAL RETURN 

The FREADBYKEY intrinsic returns a positive integer value to Igth showing the length of the infor- 
mation transferred. If the tcount parameter in the FREADBYKEY call is positive, the positive 
value returned represents a word count; if the tcount parameter is negative, the positive value re- 
turned represents a byte count. 



PARAMETERS 

filenum 

target 

tcount 



keyvalue 



keylocation 



integer by value (required) 

A word identifier supplying the file number of the file to be read 

randomly. 



logical array (required) 

An array to which the record is to be transferred. 

enough to hold all the information read. 



It should be large 



integer by value (required) 

An integer specifying the number of words or bytes to be transferred. 
If this value is positive, it signifies the length in words; if negative, it 
signifies the length in bytes; if zero, no transfer takes place. 

If tcount is less than the size of the record, only the first tcount words 
are read from the record. If tcount is larger than the physical record 
size, transfer is limited to the length of the physical record. 

byte array (required) 

A byte array containing the value that will determine which record is 
read. The first record found with this identical value in the key iden- 
tified by keylocation is the record read. 

integer by value (required) 

The relative byte location in the record of the key whose value deter- 
mines which record is read. The first byte is numbered 1; if a value of 
zero is specified, the primary key is used. 
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CONDITION CODES 

CCE The information specified was read. 

CCG The logical end-of-data or beginning-of-data was encountered during 

the read. 

CCL The information was not read because an error occurred, such as an 

input/output error, or the key could not be located. 

USING FREADBYKEY 

The intrinsic FREADBYKEY allows you to locate and read a single record according to a specified 
key value. Like FFINDBYKEY, it defines the key that is to be used for determining record se- 
quence and, following execution, remains positioned at the same record. Unlike FFINDB YKE Y, 
FREADBYKEY cannot specify a key length different from the full length of the key at creation, 
nor can it search for approximate key values. 

In the example in figure 4-8, the keylocation and keyvalue values are read from the standard input 
device. As each is read, it is printed to test the read. The first set of values read into the word 
array INFOW is: 

01 ROBERT GERRY 

V n , ' 

keylocation keyvalue 

The first two ASCII characters contain the keylocation; the characters starting in byte 2 contain 
the keyvalue to be found at the specified keylocation. Since keylocation is an integer parameter, 
the first two bytes of the byte array INFO (equivalenced to the word array INFOW) must be con- 
verted to a binary value. This is done with the statement: 

KEYLOCATION:=BINARY(INFO,2); 

The value to be used for keyvalue is contained in the byte array INFO starting in the third byte 
(byte 2 numbered from byte 0). In the declarations at the beginning of the program, the byte array 
KEYVALUE is equivalenced to the portion of the byte array INFO that starts in byte 2. 

The intrinsic FREADBYKEY can be called with the following statement: 

FREADBYKEY(FILNUM,INPUT,-72,KEYVALUE,KEYLOCATION); 

This locates and reads the first record with the value ROBERT GERRY in the key located starting 
in byte 1 of the record. The program prints this record and then returns to get the next pair of 
values input for keyvalue and keylocation. When there are no more values in the input file, the 
KSAM file is closed and the program terminates. 
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SHARED ACCESS. If you use FREADBYKEY to position the pointer for subsequent calls that 
read or update the specified record, you should lock the file with a call to FLOCK before calling 
FREADBYKEY. Then, after calling the read or update procedure, you should unlock the file so 
other users can access it. Locking the file before calling FREADBYKEY insures that other users 
do not change the position of the pointer between the call to FREADBYKEY and any subsequent 
procedure that depends on the pointer position. (Refer to table 4-2 for a list of the pointer-de- 
pendent procedures and also those that set the pointer.) 

To illustrate, the following sequence of calls makes sure that the correct record is updated: 

FLOCK- to lock the file 

FREADBYKEY- to position the pointer 

FUPDATE-" to modify the record to which the pointer points 

FUNLOCK- to unlock the file for other users 

DUPLICATE KEYS. FREADBYKEY always positions to the first key in a chain of duplicate keys. 
If you want to read or update the remaining keys in a duplicate key chain, you should use FREAD. 
For example, to update all the records with a particular key, use the following code sequence: 

FREADBYKEY- to locate 1st key in chain of duplicates 

FUPDATE- update that record 

FREAD read next sequential record 

<test if this is correct key value> 

FUPDATE- update record 

<return to read next record> 
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$CONTROU MAIN = 1 jEXAMPL3 

«• «>> 

«* EXAMPLE 3 »>> 

<<* READ A KSAm FILE RANDOMLY »>> 

<<» »>> 

|NTtSE« FJLMJhj 

INT6.3ES F.B»QPCO0£ r i.€N6?HI 

S*TE ARRAy PILNAME sO t9> ! smjexAMPIL » | 

ARRAY MESSAGEI0S35) » 

ARRAY TNPUT(0I39» I 

ARRAY OUTPUT <») *INPUTf 

SYTfc AisKAy *EYVA;.UE <* r-INFO i2H 
I^'TtSEP KfYLOCATlOMt 

I NTH [NSI Z FOPEN.FCLOSE.FREAQ , FREADBYKEY ,REAP,PRINT, 
FCHECK,FERR*SG i BINARY .TERMINATE I 

<<»»#»«»»««««<g.»0<»«»»««»««»> > 

<<• OPEN THE KSAM FILE •>> 
<<#»««««»«»««»0««»»»««»« 4 e> > 

FlLNUMt=F PE^(FILNAME,3) J <<QPEN TME KSAM FI|_E>> 

IF FILNUM3O 

THEN BEGIN <<CANNOT OPEN KSAm FILE>> 

MOvE MESSAOEt*"CANNOT OPEN KSAM FILE"! 
PRINT (MESSAGE, -31 ,0) « 

FCHECKiFlLNUM.ERRORCODE) I <<GET THE ERROR NUmbER>> 

FERRMSgIERRORCODE, MESSAGE, LENGTH) »<<GET MESSAGE STRlNG>> 

print (message,-length,o) » <<print error message>> 

TERMINaTEi 
END» 

<<» READ in KEYVALUE AND KEYLOCATION INFOMATION »>> 

Ll« 

REA0(i N F0w,-36) » 
IF > 
THEN BEGIN 

FCLOSE|FILNUM,0,0) » <<CLOsE THE KSAM FlLE>> 

IF <> THEN 
BEGIN 

MOVE MESSAGEJ»"CANNOT CLOSE THE KSAM FH.EM 
PRINT (MESSAGEi-26 ( 0) \ 

PCHECK(FILNUM,ERRORCODE) | <<GET THE ERROR NUMBER>> 

FERRMSG(ERRORCODE|MESSAGE, LENGTH) K<GET MESSAGE STRING>> 
PRINT(MESSAGE, -LENGTH, 0) I «P«INT ERROR MESSAGE>> 

END I 
TERMlNflTE| 
END | 
IF < 
THEN BEGIN 

MOvE M ESSAGE J ""ERROR OCCURRED WHILE READING INPUT" j 

PRINT < MESS AGE i-3<»t0) | 

TERMINATEl 



Figure 4-8. FREADBYKEY Example 
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PRINT( INF W,-36iO) | <<TEST »EAD>> 

KEYLOCfiTIOM|xpINARY( INFO.ai J <<CONVE"T FROM ASCII TO &INARY>> 

<<ea«»eO«<>»«eeoo«<>i>»«««<>«e«4>a»»ae<>»««j>»«eoe»«4>»»»»<»«o«>> 

<<# READ KSAm ACCORDING TO KEYVALUE AND KEyLOCATION #>> 

<<*#»««»»«*•»•»♦*»*«»»»»«■■»»»»»»***«»**«**»*«***•»»**»»»>> 

rRE^eBYKEY { rj,.MUM f IMpJ/Ti-3f2»«E ,rV ,*-i-U?,K«;yi,CC» ' I SMI *. 

IF <> 

THEN BEGIN <<ERROR OCCURRED IN FRFBDBYKEY>> 

MOVE MESSAGE! s»ERROR OCCURRED IN FREADBYKEY" | 
PRlNT<MESSAGE»-28,0> I 

FCHECK(FILNUM,ERRORCODE) » <<r,ET THE ERROR NUMBER>> 

FERRmSg<ERRORCODE|MESSAGE, LENGTH) |<<GET MESSAGE STRING>> 
PRINTImeSSASE, -LENGTH, 0) » <<pRJNT ERROR M£SSAGE>> 

GO TO LI* 
END! 

<<« WRITE THE DATA JUST READ FROM KSflM FILF »>> 
<<«ft«ea*«»«ttft««««»««ft»a»««*«»«**»»«««««««««»a«««e>> 

PRlNT(OUTPuTi-72,0) I 

<<« go Back to get another record »>> 

GO TO Lll 
ENDJ 



Output from Program Execution: 

ftH?0«*FRT GERRY 

?06E*T GtRRY 2b9-553S U3a5 TELEGRAPH A V E. BERKELEY HA. 9087j 

Eckstein l£0 287-5137 5303 stevens c»eek santa cla^a ca, 95050 



END OF PROGRAM 



Figure 4-8. FREADBYKEY Example (continued) 



4-67 



FREADC 



INTRINSIC NUMBER 305 

Reads a logical record in chronological sequence from KSAM file to user's stack. 

1 IV LA IV 

lgth:=FREADC(filenum, target, tcount); 

FREADC reads a logical record in chronological sequence. Chronological sequence means the se- 
quence in which the records were originally written to the data file. 

When FREADC is executed, the key file is not accessed. This read is similar to the standard FREAD 
for non-KSAM files except that FREADC skips any data records that are marked for deletion. Fol- 
lowing execution, the chronological pointer remains positioned at the same record. 

FUNCTIONAL RETURN 

The FREADC intrinsic returns a positive integer value to Igth showing the length of the information 
transferred. If the tcount parameter in the FREADC call is positive, the positive value returned 
represents a word count; if the tcount parameter is negative, the positive value returned is a byte 
count. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be read in 
chronological sequence. 

target logical array (required) 

An array to which the record is to be transferred. This array should 
be large enough to hold all the information to be transferred. 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be transferred. 
If this value is positive, it signifies the length in words; if negative, it 
signifies the length in bytes; if zero, no transfer occurs. 

If tcount is less than the size of the record, only the first tcount words 
are transferred from the record. If tcount is larger than the physical 
record size, transfer is limited to the length of the physical record. 

CONDITION CODES 

CCE The information was read. 

CCG The logical end-of-data was encountered during reading. 

CCL The information was not read because an error occurred. 



4-68 



FREADC 



USING FREADC 

This intrinsic allows you to read the records in the data file in the order in which they are physically 
stored in the file. The end-of-data is encountered following the last record in the file. If any records 
have been marked for deletion (refer to the FREMOVE intrinsic), these records are not read; other- 
wise, this intrinsic reads the data from the data file exactly as it was stored. 

Following execution of FREADC, the chronological pointer remains positioned at the record just 
read, unless it is followed by another call to FREADC. In a series of calls to FREADC, the pointer 
is advanced automatically so you can read the file in chronological sequence without resetting the 
pointer for each record. 

Because FUPDATE only checks the logical pointer, you cannot update a record located by 
FREADC or FREADDIR. To update a record located by its chronological record number, you 
must precede the call to FUPDATE with a call to FPOINT. Unlike FREADC or FREADDIR, 
FPOINT sets the logical pointer as well as the chronological pointer. 

In figure 4-9, the FREADC intrinsic is used to read the data from the KSAM data file in chronologi- 
cal order. Compare this order to the sequential order by primary key in which the same file is read 
by FREAD. (Refer to figure 4-10 for an example showing the chronological record number printed 
in association with each record listed in sequential key order.) 

SHARED ACCESS. Because FREADC is a pointer-dependent procedure, you must call one of the 
procedures that position the pointer before calling FREADC. (Refer to table 4-2 for a list of the 
pointer-dependent and pointer-independent procedures.) When access is shared, it is essential that 
you lock the file before calling the procedure that positions the pointer, and then leave the file 
locked while it is being read by FREADC. This insures that no other user changes the position of 
the pointer after the call that positions the pointer or between sequential calls to FREADC. 

For example, the following sequence of calls guarantees that you will read the file in chronologi- 
cal sequence starting with a specified record number: 

FLOCK- lock file 

FPOINT- position the chronological pointer 

FREADC loop read records in chronological sequence 

FUNLOCK- unlock file 
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SCONTROL MAIN*JEXAMP|> 

«* • » 

<<* EXAMPLE 4 «>> 

<<* READ A KSAM FILE CHRONOLOGICALLY •>> 

<<# •» 

INT£G£'R FIwHUMJ 

fHTtS£R F.R«ORCOOE{ 

©Vlfc array FIUNAME »ai9J f *"JE*«t«FTL » I 

ARRAY MESSAGE (0J35) J 

ARRAY INPUT(0»39) I 

ARRAY OUTPUT (#) aINPUTI 

INTRINSIC FOPEN i FCLOSE, FREADC, FCHECK.FFRRMSS, PRINT .TERMINATE ? 

<<* OPEN THE KSAM FILE «>> 

?SvNUM{*fOP£NsFISu>«f<s£,3» i «{>PJ;N Tt'E KSAM FtL^> 

IF FlLNUMsO ^ "" """" 

THEN BEGIN 

M OvE MesSAGE«s"CANNOT OPEN KSAM FILE"! 

print < mess age, -si , o> i 

FCHECK(FILNUM,ERRORCOOE) » <<GET THE FRROR NUMBE*>> 

FERRMSGtERRORCODE, MESSAGE, LENGTH) »<<GET MESSAGE STRlNG>> 

PRINT(meSSAGE,-LENGTH i O) I <<PRINT ERROR MeSSaGE>> 

TERMINATE! 
END | 
LI! 

<<» READ KS*M ACCOROING TO CHRONOLOGICAL ORDER #>> 

FNgACctflLMUM, INPUT. *TgS i 

IF > " " ' 

THEN BEGIN <<ENO OF FlLE>> 

FCLOSE(FILNUM,0,0) 1 <<CLOSE ThE KSAm file>> 
IF <> 

THE N BEGIN 

move messages* m cannot close ksam file"i 
print(message,-22,0> » 

fcheck(filnum.errorcooe) i <<get the error number>> 
ffrrmsgterrorcode, message, length) k<get message string>> 

PRINTIMESSAGE, -LENGTH, 0) 1 <<PRInT ERROR MESSAGE>> 

ENoi 
TERMINATE! 
END! 
IF < 
THEN BEGIN 

MOVE MESSAGE I ""ERROR OCCURRED WHILE READING kSaM FILE"! 

PRlNT(MESSAGE,-37»0) | 

TERMINATE! 
END! 

<<• WRITE THE DATA JUST READ FROM KSAM FILE *>> 

PRINT (OUtPUTi-72,0) I 

«» GO 8aCK TO GET ANOTHER RECORD «>> 

GO TO Li! 
END! 



Figure 4-9. FREADC Example 
4-70 



Output from Program Execution: 



FREADC 



N0L4M .JACK 923-<»97S 967 REED AVE, 

H0S03A JOE 227-821* lj8o SAINT PETER CT. 

Eckstein leo 287-5137 5303 stevens cheek 

CarOIN PICK 578-7018 HloO WOL?E ROAQ 

PaSBY Ll N DA 295-1187 TOWN 4. CNTRY VILLAGE 

SEELY hENRy 293-4220 n4«, LEBERTY ST, 

ROBERT GERRY 259-5535 12345 TELEORAPH AvE. 

TLRNfWR IVAM 984*8498 22<»0S EMERSON ST. 

XHITE GORDON 3*8-0301 43So ASHBY AVE, 

WESTER ELOER 287-4598 1256. MNSFISHER- ST. 



Sunnyvale ca, 94ofl7 

los autos ca, 9*022 

Santa clara ca. ssoso 

cupertino ca, 94053 

san jose ca. 94102 

EL CERRlTn CA, 940S3 

8epkeley ca. 90jbtj 

Oakland ca. 96234 

BERKELEY «*. 91234 

Sunnyvale ca, 43CM9« 



END OF PROGRAM 



Figure 4-9. FREADC Example (continued) 



4-71 



FREADDIR 



INTRINSIC NUMBER 7 

Reads a logical record located by its chronological record number from a KSAM file to the user's 
stack. 



IV LA IV DV 
FRE ADDIR( f He num, target, tcountjecnum) ; 



The FREADDIR intrinsic reads a specific logical record, or a portion of such a record, from a 
KSAM file to the user's data stack. The particular record read is specified by its chronological 
record number. This number is determined by the order in which the record was written to the 
file; it is not the logical record number determined by ascending key sequence. When the file has 
fixed-length records, recnum is the actual record number counting from the first record in the file. 
When the file has variable-length records, recnum is a word pointer to the first word in the record 
counting from the first word in the file, word zero. 

After FREADDIR has been executed, the chronological record pointer remains positioned at the 
record just read. FREADDIR does not change the position of the logical record pointer. 



PARAMETERS 

filenum 



integer by value (required) 

A word identifier supplying the file number of the file to be read. 



target 



logical array (required) 

An array to which the record is to be transferred. This array should be 

large enough to hold all of the information to be transferred. 



tcount 



integer by value (required) 

An integer specifying the number of words or bytes to be transferred. 
If this value is positive, it signifies words; if negative, it signifies bytes; 
and if it is zero, no transfer occurs. 



If tcount is less than the size of the record, only the first tcount words 
or bytes are read from the record. If tcount is larger than the size of 
the logical record, the transfer is limited to the length of the logical 
record. 



recnum 



double by value (required) 

A double-word integer indicating the relative chronological record 
number (or word number for variable-length records) to which the 
chronological pointer is positioned. Chronological record numbering 
for fixed-length records starts with zero or one, as specified in 
ksamparam or by FIRSTREC in BUILD. 
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CONDITION CODES 

CCE The specified information was read. 

CCG The end-of-data was encountered during reading. 

CCL The information was not read because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FREADDIR 

The FREADDIR intrinsic can be used to position to a particular record in chronological sequence 
and then read that record. Following execution, the record pointer remains positioned at the same 
record. This intrinsic is thus identical in effect to the pair of intrinsics: FPOINT and FREADC. 
You might use FREADDIR to read one record and then reposition the pointer; you might use 
FPOINT and FREADC to position to a particular record and then continue reading in chronological 
order from that position. 

You can use the FGETINFO intrinsic to determine the relative chronological number of the record 
most recently accessed. This number is returned in the FGETINFO parameter recpt. The example 
in figure 4-10 determines the chronological record of each record as it is read in sequence by pri- 
mary key value. The chronological record number is printed, and then FREADDIR uses this num- 
ber to read the record to which it points. The output shows the chronological record number fol- 
lowed by the record to which it points. To see these records listed in chronological order, refer to 
the output in example 4-9 illustrating FREADC. 

Note that execution of those intrinsics that position the KSAM data file by means of the chrono- 
logical record pointer (FPOINT, FREADC, FREADDIR), do not access the key file. This type 
of access only affects the data file. It is, therefore, much faster than those intrinsics that use key 
sequence to position the data file and must access the key file. 
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SCONTROL MAIN*JEXAMPl_6 


«««»««>»«»«««ii«««»««»<i<«t«te««i>««ii««c»«««{)iit9t«i>a»9«»it» ( «4>> 


<<• 


«>> 


<<# 


EXAMPLE 6 »>> 


<<* 


READ A KSAM FILE BY CHRONOLOGICAL RECORD NUMBER »>> 


<<* 


»>> 


<<««»««««»«««««««»«««•««»««««««*«««««»««»<»»»««««»»««»»»«»»«>> 


INTtOEK FIUNUMS 


• KlTL / 


- ,#« « ™ _-. -. -_ ._■_.— .._ 


IsviLts^n 5 stiyciot i 


J»s'TliSES LENGTH I 


BVTt 


SFtR&y FIUMM£ C3$9J|S» j£aA!4FJL "1 


ARRAY MESSA6E(0l35) » 


ARRAY INPUT(0I39>| 


ARRAY OUTPUT!*) "INPUTI 


DOUoLe R£CPTe?f 


INTRINSIC FOPENiFCtOSE.FREAD.FQETINFO.FREADOlRt 




PR IMT, TERMINATE, DA SCI I . FCHEc* , FERRMSG | 


<<««»«««»*««««»«««*•*•««««>> 


<<« 


OPEN THE KSAM FILE »>> 


<<•«•««•««««•«•«••*««•««•«>> 


FfLNUXjaFOfK^'.PlL.NftMe' *3> » «<G»6'« THfc KS&M FJL£» 


IF FILNUMsQ 


THEN 


BEGIN <<CANNOT OPEN KSAM FILE>> 




MOVE MesSAGEI«"CANNOT OPEN KSAM FILE"I 




PRINT(MESSAGE»-2I tO) I 




FCHECK(FlLNUM,ERRORCODE) I <<G£T FRROR NUMB£R>> 




FERPMS(3(ERRORCOOE, MESSAGE, LENGTH) K<CONVERT TO STRING>> 




PRINTIMESSAGE, -LENGTH, 0) 1 <<PRINTOUT ERROR MEgSAGE>> 




terminatei 




END) 


<<»*«««*««««««««»«•««»«*«»««««»«•»««*««»««»#•««•«»««»»>> 


<<* 


READ KSAM SEQUENTIALLY •>> 


««•«»«««»«««««»<*••««««»««««««*»»«*««««»»>»»<»••»«»»«» 


111 




FREAD(FlUNUM,INPUT,-72) I 


IF * 
THEN 


BEGIN 




FCLOSE(FILNUM,0,0) 1 <<CLOSE THE KSAM FILE>> 




IF <> THEN 




BEGIN 




MOVE MESSAGEJ*"CANNOT CLOSE THE KSAM FILE"! 




PRINT { MESS AGE, -22,0 I T 




FCHECK(FILNUM,ERR0RCODE) 1 <<GET ERROP NUM8ER>> 




FFRRMSGIERRORCODE, MESSAGE, LENGTH) |<<CONVeRT To 5TRING>> 




PRlNT(MESSAGE,-LENGTH t O) I <<PRINT0UT ERROR MESSAGE>> 




ENDI 




TERMINATEI 




ENDI 


IF < 




THEN 


BEGIN 




MOvE MFSSAGE«»"ERROR OCCURRED WHILE READING KSAM FILE"! 




PRINT<MESSAGE,-3T,0) » 




FCHECK(FILNUM,ERRORCOOE) i <<GET ERROR NUMBE R >> 




FERRMSq<ERRORCODE, MESSAGE, LENGTH) |<<C0NVERT TO STRINg>> 




PRINT(meSSAGE, -LENGTH, 0) » <<PRINTOUT ERROR MESSA6E>> 



Figure 4-10. FREADDIR Example 
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TERMINATEl 

endj 

<<*» TO FIND out record number of THE RECORD JUST READ »>> 

<<«««««»it«««<i»ft»*i»»»»«««»*«»ft«» ,> #e««««ii««ii«»»*<)»«4<««««» 

F9ET iNFOlFltWUW,,, , » »», ,R£CpTR} f 

MOVE MESSAGE! s»RECORO« = "I 
DA SCI I (RECPTR, 10 (MESSAGE (5 > ) I 
PRINT(MESSAGE,-1*.0) I 

<<» READ THE KSAM FILE BY USING RECORD NUMBER »>> 

IF <> 

THEN BEGIN 

MOVE MesSAGEI»"ERROR OCCURRED DURING FREADDIR"! 

print (message 1-30 10) i 

FCHECK<Fl|_NUM,ERRORCODE> » <<get frror numbe«>> 
FERRMSgIERRORCODE, MESSAGE, UENGTHJ l«CONVERT TO ST»INg>> 
PRINT (MESSAGE, -UENGTh.O) » <<PRINT0UT ERRO* MEsSAGE>> 

terminatei 

END) 

<<#«•••••#»•*»•••#••••♦»•»»»•••*#•»•••••»«#•##•**>> 

<<• write the data just read by freaddir •>> 

print(output,-72,0) i 

<<» go Back to get another record #>> 

<<•••••#•»♦••#•#•*#•••»•»•»«•»•*»»***>> 

GO TO Lll 

ENDJ 



Output from Program Execution: 



P-ZCS*0# 


z 


••* 




CAiSOIK 




3sCK 


ST8-?eiS 


*«FCCi*0* 


,g 


1 




EckSTFIN 


,.„;," 


LtO 


aS?»5I3? 


RiiCD*D« 


* 


fi 




HOS03A 




JOE 


ea?»3ai<* 


»£trsac-# 


ifti 


si--' [■" !J ",j' t :.« 




ncla^j 




J**CK 


Sg3-*9?S 


RECCSp* 


z 


■i 




^ASSY 




1. 1 NO A 


2*5»1},S? 


second** 


; 


? 




; ' RCdE'T 




GERRY 


£*9"S!535 


Sg'SO^D* 


z 


& 




SEELY 




■*£nry 


a^3«**320 


Record* 


i 


* 




tlji*SfW«! 




IVAN 


98«»»»*9S 


RgC05?!7* 


"at 


10 




WESTER 




EwSEs 


2S?~4835 


Rcco*c# 


. 


<"•* 




*«IT£ 




GORDON 


39B-0301 



111 ^0'„F£ Rr.ftft 
S30 j STEVENS CR££* 
UBo 56INT PETES Ct, 

'OWN 4 CNfWV V?uL«$g 
123*5 TELEGRAPH > AvE. 
11*4 LEBEHTY ST, 

Sg^?S EM£R$OH ST, 
125ft KINGFISHER ST, 
4 3* a ASH3V Ave, 



CUPCOTJNO 
SANTA CtftSft 
LOS ALTOS 

Sunnyvale 
SJSN jo s t 

£t CT.PrITO 
Qa*u A«n 
SUNN WALE 
«E«KCl.FY 



CA, 9*053 

.-" . "• ; » ■-":: 

' t. . i - s ■ 

-A. 9*10? 

CA. 90871 

C*. 94053 

ca, 9a as* 

CA, <,309B 

CA, 9U3V 



END OF PROGRAM 



Figure 4-10. FREADDIR Example (continued) 
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INTRINSIC NUMBER 19 
Reads a user file label. 



^.v- : '-A' ; 'Vv^v- IV ^ LAI* ;, IV IV 
FREADLABEL(/i'tenum, target, tcoun t, labelid) ; 



0-V 



The FREADLABEL intrinsic reads a user-defined label from a disc file. Before reading occurs, the 
user's read-access capability is verified. Note that MPE automatically skips over any unread user 
labels when the first FREAD intrinsic call is issued for a file; therefore the FREADLABEL intrinsic 
should be called immediately after the FOPEN intrinsic has opened the file. 



PARAMETERS 

filenum 
target 



tcount 



labelid 



integer by value (required) 

A word identifier supplying the file number of the file whose label is to 

be read. 

logical array (required) 

An array in the stack to which the label is to be transferred. This array 

should be large enough to hold the number of words specified by 

tcount. 

integer by value (optional) 

An integer specifying the number of words to be transferred from the 

label. Tcount must not be greater than 128 words. 

Default: 128 words. 

integer by value (optional) 

An integer specifying the label number where the first user label is 

numbered 0. 

Default: A default value of is assigned. 



CONDITION CODES 

CCE The label was read 

CCG The intrinsic referenced a label beyond the last label written on the file. 

CCL The label was not read because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 
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USING FREADLABEL 

If the KSAM file contains one or more user labels (written with FWRITELABEL), you can read 
these labels with the FREADLABEL intrinsic. During the normal file reads with FREAD, FREADC, 
FREADBYKEY, or FREADDIR, any user labels are ignored. The number of user labels that can 
be written to the file is specified by the userlabels parameter of FOPEN, or in the BUILD command 
of KSAMUTIL. 

Since MPE checks to insure that you have opened the file with read access before executing 
FREADLABEL, you must open the file with an FOPEN aoptions setting that permits reading. It 
must be one of the following: 

bits 12:4 = 0000 (octal 0) read only access 

= 0100 (octal 4) input/output access 
= 0101 (octal 5) update access 

In addition, the FOPEN userlabels parameter must be set to a value of 1 or greater depending on 
the number of labels that may be written to the file. 

Suppose you have opened the file KDATA with the following call: 

KFILNUM:=FOPEN(KDATA,3,4, , , , 2); 

old user/ \ number of labels 
domain 

input /output access 

You might read the second label with the following call: 

FREADLABEL(KFILNUM,LABELBUF, , 1) 

This reads the second label into the array LABELBUF. Note that label numbering begins with 0; if 
the labelid parameter were zero or omitted, then the first label would be read. By default, the num- 
ber of words read from the label is 128. 
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INTRINSIC NUMBER 12 

Moves a record from a disc file to a buffer in anticipation of a FREADDIR intrinsic call. 

NOTE 

This intrinsic may not be used for KSAM files. If called for a file 
created as a KSAM file, the intrinsic returns a CCL condition code. 
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INTRINSIC NUMBER 18 

Determines whether a file pair is interactive, duplicative, or both interactive and duplicative. 

NOTE 

This intrinsic may not be used for KSAM files. If called for a file 
created as a KSAM file, the functional return is set to zero (FALSE) 
and the condition code CCE is returned. 
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INTRINSIC NUMBER 306 

Marks the current record in KSAM file for deletion. 



-,v;-> iv 

FREMOVE(filenum); 



The intrinsic FREMOVE effectively removes the current record from the KSAM file. When exe- 
cuted, the first two characters of the current record in the data file is set to all l's, and all key 
entries pointing to this record are deleted from the key file. Although the space required by the 
record remains in the data file, it is no longer possible to access the record through KSAM intrinsics. 

In order to position the file to the record to be deleted, FREMOVE must be preceded by one of 
the intrinsics that positions the logical record pointer: FFINDN, FFINDBYKEY, FREADBYKEY, 
FREAD, FPOINT, or a previous FREMOVE. Following execution of FREMOVE, the logical 
record pointer is positioned at the next record in ascending key sequence. 

FREMOVE checks only the logical record pointer, not the chronological pointer, to locate the 
record to be deleted. Therefore, if you want to delete a record located by its chronological posi- 
tion in the file, precede the call to FREMOVE with a call to FPOINT. FPOINT locates the record 
by its record number and sets the logical, as well as the chronological pointer, to that record. If 
you try to locate a record for FREMOVE by calling FREADDIR or FREADC, which only set the 
chronological pointer, you will delete the wrong record. 

When FREMOVE is executed, a check is made to make sure the record to be deleted actually con- 
tains the key value to which the pointer is positioned. If the record does not contain that value, 
then a condition code (CCL, error=191) is issued and the record is not deleted. 

If the file was opened for shared access (aoptions bits 8,9 = 11) then you must call FLOCK before 
calling FREMOVE. Note that the file must also have been opened with dynamic locking allowed 
(aoptions bit 10 = 1). 

NOTE 

If you want to recover the data in deleted records through non- 
KSAM access (using FCOPY with the NOKSAM option), do not 
place any data in the first two bytes since these bytes are over- 
written by FREMOVE. 



PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file from which the 
record is to be deleted. 
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CONDITION CODES 

CCE The current record is deleted. 

CCG The logical end-of-data was encountered. 

(XL An error was encountered or record does not contain requested key 

value; the record is not deleted. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FREMOVE 

When FREMOVE is executed, it sets the first word (bytes 1 and 2) of the current record to all l's. 
It does not physically delete the record from the file. When the file is read by any of the KSAM 
read intrinsics, the deleted records are skipped as if they were not there. Since all references to 
them are deleted from the key file, the speed of execution is not usually affected by the records 
physically remaining in the file. However, they do take up space and if a great many records are 
deleted, then you might want to build a new KSAM file and copy the old file to the new file with 
FCOPY. Since FCOPY does not copy records marked for deletion (except with the NOKSAM 
option), the new file will be shorter and have no space used by deleted records. (Refer to section 
II for a description of copying KSAM files with FCOPY.) 

The example in figure 4-11 deletes all records with a telephone number in the alternate key field 
that is equal to or greater than "500-0000". The FFINDBYKEY intrinsic positions the file to the 
record containing the lowest alternate key value that is greater than or equal to "500-0000". This 
record is then read and printed prior to being deleted by FREMOVE. Following FREMOVE, the 
program loops back to read the next sequential record, print it, and then delete it. When an end of 
data is reached, the program terminates. In all, the program deletes three records. You can check 
the deleted records against the list of records printed in telephone number sequence by the program 
illustrating FREAD in figure 4-7. 
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In practice, an FREAD prior to an FREMOVE is useful because it allows you to test the record 
contents prior to deleting the record. For example, you might want to delete only those records 
with the zip code 90871 in bytes 75 through 79 of the record, assuming the same file as in 
figure 4-11: 

BYTE ARRAY INPUTB(*)=INPUT; - equate the byte array INPUTB to INPUT 



LI: 

FREAD(FILNUM,INPUT,-72); 
IF> 

. -« test for end of data 

IF< 

. -« test for read error 

IF INPUTB(75)="90871" 
THEN BEGIN 

FREMO VE( FILNUM) ; 

IF< 

. ^ test for delete error 



END; 
GO TO LI; -« return for next record 



SHARED ACCESS. In a shared environment, you must always lock the file with a call to FLOCK 
before calling FREMOVE. Furthermore, since the logical record pointer must be positioned before 
the call to FREMOVE, you should lock the file before calling the procedure that positions the 
pointer. This prevents other users from affecting the pointer position by adding or deleting records 
between the time you position the pointer and call FREMOVE. The following sequence of calls 
illustrates the correct method for deleting a record in a shared environment: 

FLOCK- lock the file 

FREADBYKEY- position pointer and read record 

FREMOVE- mark the record for deletion 

FUNLOCK- unlock file to allow access to other users 

Remember to open the file for shared access and allow dynamic locking whenever you plan to 
delete records from a file in a shared environment. 
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$CONTROL MAIN,j£XAMPI_7 



< v- 



EXAMPLE 7 «>> 

<<• DELETE SELECTED RECORDS «>> 

iNTtGER FILNUMJ 

INTEGER LENGTH! 

INTEGER fRRORCODEi 

BYTE ARRAv F I LNAME ( I 9 ) I *» JEXAMF IL "I 

ARRAY INPUT I0J39) I 

ARRAY ni.'TPDT («i =IMPU T » 

8YTE ARRAY KEYVALUE ( t 7 ) J s"500-0000" I 
INTEGER KEYLEMGTHl»8» 
INTEGER KEYL0CATI0NJ=2l» 

INTEGER RELOPIspl << GREATER THAN OR EQUAL TO >> 
INTRINSIC F0PENiFCLOSE,FREAD,FRtM0VE,FFlND8YKEY, 
3EAO»PRINT,T£RMlNATE^FCH£CK,F£R«MS6| 

<<» OPEN THE KSAM FILE *>> 

FlLNUM|»FOPEN(FILNAME,3 t 5) I <<OPEN THE KSAM FILE FOR UPDATE>> 

IF FILNUM.O 

THEN BEGIN <<CANNOT OPEN KSAM FILF>> 

MOVE MESSAGE J a"CANNOT OPEN KSAM FILE"! 

PRINT(MESSAGEt-21»0) I 

FCHECK(FILNUM.ERRORCODE) » <<GET ERROR NUMBER>> 

FERRMSs«ERRORCODE, MESSAGE, LENGTH) |<<CONVERT TO STRING>> 

PRINT«MESSAGE,-LENGTHf 0) » <<PRINTOUT ERROR MEsSAGE» 

TERMINATE I 

end i : ' ': : " ."; • - ■' ' 

«* POSITION KSftM FILE IN TFLFPMCNE 4 SEQUENCE •» 

FFlNDBYKEY(FlLNUM,KEYVALUE,KEYLOCATION f KEYLFNGTH,RELOP) I 
MOVE MESSAGEJ »«'DELETE FOLLOWING ReCORDSi"! 
PRlNT(MESSAG£,-a5,0) I 

<<* RE*D RECORD BEFORE DELETING «>> 

L2I 

FRE«D(FILNUM. INPUT, -72) I <<REAd RECORDS To BE OELETED>> 

IF > 

THEN BEGIN <<ENR OF FILE» 

FCLOSE(FILNUM,0,0) J <<cLOSE THE KSAM FILE>> 
IF <> THEN 

BEGIN <<CLOSE UNSUCCESSFUL>> 

MOVE MESSAGEI«"CANNOT CLOSE THE KSAM FILE»I 
PRlNT(MESSAGE,-29,0) » 

FCKECK(FILNUM,ERRORCODE) I <<GET ERROR NUMbER>> 
FERRMSG<ERRORCODE, MESSAGE, LENGTH) |<<CONVERT To STRING>> 
PRINT(MESSAGE,-LEMGTH,0) J <<pRINTOUT ERROR MesSAGE>> 
ENO» 
TERMINATE! 
END} 



Figure 4-11. FREMOVE Example 
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IF < 

THEN BEGIN 

MOVE MESSA6EI»"ERROR OCCURRED WHILE READING INPUT"! 
PRlNT(MESSAGE|-34»0) I 

FCHECK<FtLNl)M,ERRO«CODE> » <<G£T FRROR NUMBE«>> 
FERRMSglERRORCODE, MESSAGE, LENGTH) |<<cONVERT TO STrINg>> 
PRINTIMESSAGE, -LENGTH, 0)i <<PRINTOUT ERROR MEsSAGE>> 
TERMINATE! 
ENUJ 
«*«««««»«««>»<»«»»»*«»«<«««»»*t»»*»«*«it»i)«tii«» 
<<• WRITE THE RECORD JUST READ FROM KSAM FILE «>> 
<<**««««» <l ««««»»««««e«««««»««ff«««»tt«»«*»0»«»««e«»>> 

PRlNT(OUTPUT,.7a,0) I 

«« REMOVE RECORD JUST READ F«OM FILE #>> 

: -- ■■-..:. r U. '*■-".■ i <«DELETt ?ECORD>» 

IF< 

then begin 

move message i «"error occurred during delete"* 

PRlNTfMESSAGE,-28,0) I 

FCHECK(FILNUM.ERRORCODE) i <<9ET ERROR N!JMBE R >> 

FERRMSsiERRORCODE, MESSAGE, LENGTH) |<<rONVERT TO STRINe>> 
PRINT(MESSAGE, -LENGTH, 0) I <<PRINTOUT ERROR ME S SAQE>> 
TERMINATE! 
END! 

<<« GO BACK TO GET ANOTHER RECORD »>> 
<<««««««»»«*«»«*»««««*<t«««««»«»»»««t>o>> 
GO TO L2» 
ENO! 

Output from Program Execution: 

OELE' ' •-.....' [\G RECORDS! 

CAROIN RICK 5T8-701B JilOO WOLFE ROAD CuPERTjNO CA, 9fc053 

MOLi^J JACK S23-*97b 967 REEO *-■:.- SUNNWi E CA ->.-ii* 

TUHNCWR IVAN 984-B498 ??9 S EMERSON ST. OAKLAND CA. 98234 
ENO OF PROGRAM 



Figure 4-11. FREMOVE Example (continued) 
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INTRINSIC NUMBER 17 



Renames a disc file. 



NOTE 

This intrinsic may not be used for KSAM files. If called for a 
file created as a KSAM file, the intrinsic returns a CCL condition 
code. 

To rename a KSAM file, use the KSAMUTIL RENAME command. 
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INTRINSIC NUMBER 14 
Activates or deactivates critical output verification 



IV LV 

FSETMODE(filenum, mode flags); 

The FSETMODE intrinsic activates or deactivates the access mode option that permits critical out- 
put verification. This means that all output must be verified as physically complete before control 
returns from an output intrinsic (FWRITE,FUPDATE, or FREMOVE) to your program. 

The access mode established by the FSETMODE intrinsic remains in effect until another 
FSETMODE call is issued or until the file is closed. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to which the 
call applies. 

mode flags logical by value (required) 

A 16-bit value that denotes the access mode options in effect. For 
KSAM files only bit 14 is used; all the remaining bits are set to zeros. 

Bit 14=1 — Activate Critical Output Verification 

When this bit is set, all output to the file is verified as 
physically complete before an FWRITE, FUPDATE, or 
FREMOVE intrinsic returns control to the user. As soon 
as a logical record is written, a CCE condition is returned 
to the user. 

Bit 14=0 — Deactivate Critical Output Verification 

When the bit is cleared, output is no longer verified. 

CONDITION CODES 

CCE Request granted. 

CCG Not returned by this intrinsic. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 
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USING FSETMODE 

When FSETMODE is executed with the modeflags parameter equal to 2 (bit 14=1), then each 
logical record written by an output intrinsic is physically transferred to the file immediately. Con- 
trol is not returned to the user program until the transfer has been made. At that time a CCE con- 
dition code is returned to the program. 

When FSETMODE is executed with the modeflags parameter equal to zero (bit 14=0), output is 
treated in the standard manner. That is, when an output intrinsic writes a logical record, the record 
is physically transferred to the file only when the entire physical record (block) of which it is a 
part is transferred. (Calls to FWRITE, FUPDATE, and FREMOVE send output to the KSAM file.) 

For example, the following intrinsic call activates critical output verification: 

FSETMODE(FILNUM,2); 
If you want to return to normal output mode, you can use the call: 

FSETMODE(FILNUM,0); 

When the file is first opened and when it is opened subsequently following an FCLOSE call, the 
critical output verification mode is deactivated. 
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INTRINSIC NUMBER 5 



Spaces forward or backward on a file. 

W IV 

i'SP A CEij'ilen urn, displace men t ) : 

The FPSACE intrinsic allows you to space forward or backward a specified number of records on 
a KSAM file. The logical record pointer is repositioned by FSPACE in key sequence. The spacing 
is based on primary key sequence unless an alternate key has been specified in a prior call to 
FFINDN, FFINDBYKEY, or FREADBYKEY. 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file on which spac- 
ing is to be done. 

displacement integer by value (required) 

An integer indicating the number of logical records to be 
spaced over, relative to the current logical record pointer position. 
Record sequence for spacing is based on key sequence. A positive 
value signifies forward spacing, a negative value signifies backward 
spacing; zero signifies no spacing, but sets a flag so that the next call 
to FREAD does not move the logical record pointer before reading 
the record. The maximum positive value is 32767; the maximum 
negative value is -32768. The sign is optional for positive values. 



CONDITION CODES 

CCE Request granted. 

CCG A logical end-of-file indicator was encountered during spacing. The 

logical record pointer is at the beginning-of-file if displacement was 
negative, to the end-of-file if displacement was positive. 

CCL Request denied because an error occurred. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FSPACE 

If you want to space back a particular number of records in key sequence, you would specify a 
negative value for the displacement parameter in a call to FSPACE. To space forward, you would 
use a positive or unsigned integer as the displacement value. In either case, the displacement indi- 
cates the number of records to space over. 
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For example, suppose the following sequence of primary key values: 
ABLE 
BAKER - (2) pointer after FSPACE(FILNUM,-2); 



CHARLIE 
DOG- 



(?) current record pointer 



EASY 
FOX- 



(3) pointer after FSPACE(FILNUM,4); 

Suppose the current record pointer is at the beginning of the record whose primary key contains 
the value DOG. To position the pointer to the beginning of the record with a primary key value 
BAKER: 

FSP ACE( FILNUM,-2) ; 

To space forward from the beginning of the record with BAKER as the key value to the beginning 
of the record with FOX as the key value: 

FSPACE(FILNUM,4); 

figure 4-12 shows that the movement of the pointer bears no relation to the physical placement of 
records in the file. 



FOX 



BOF 



ABLE 



EASY 



DOG 



CHARLIE 



marked for deletion 



BAKER 






... 



;2)FSPACE(FILNUM,-2) 
(?) pointer before FSPACE calls 
(3) FSPACE(FILNUM,4) 



— EOF 



Figure 4-12. File Position with FSPACE 
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POINTER POSITION. FSPACE checks a flag to determine whether to advance the pointer before 
it moves the pointer the specified number of records. If FSPACE follows a call that reads the file 
(FREAD or FREADBYKEY) then it advances the pointer to the record in key sequence following 
the record just read. After advancing the pointer, FSPACE positions the pointer as indicated in the 
call. If, on the other hand, FSPACE follows FPOINT, FFINDBYKEY, or FFINDN, the pointer 
remains positioned to the record specified in one of these calls until FSPACE is executed. 

To illustrate, consider the following calls: 

FREAD - read record, set flag to advance pointer 

FSPACE(-l)- test flag, advance pointer, then move pointer back 1 record 

FREAD-" reread record just read 

SHARED ACCESS. Because FSPACE is a pointer-dependent procedure (see table 4-2), it is essen- 
tial to lock the file before the call that determines the original pointer position, then call FSPACE, 
then call any other procedures that depend on where FSPACE positioned the pointer. When all 
the pointer-dependent procedures are complete, then unlock the file for other users. To illustrate : 

FLOCK- lock file 

FFINDBYKEY- locate a particular key value 

FSPACE- move pointer relative to that key position 

FREAD- read the record to which pointer is positioned 

FUNLOCK- unlock the file 
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INTRINSIC NUMBER 16 



Dynamically unlocks a KSAM file. 

IV 
F\JNLOCK{ filenum ); 

The FUNLOCK intrinsic dynamically unlocks a KSAM file (Resource Identification Number) that 
has been locked with the FLOCK intrinsic. 

PARAMETERS 

filenum integer by value (required) 

A word supplying the file number of the file to be unlocked. 

CONDITION CODES 

CCE Request granted. 

CCG Request denied because the file had not been locked by the calling 

process. 

CCL Request denied because the file was not opened with the dynamic 

locking aoption of the FOPEN intrinsic, or the filenum parameter is 
invalid. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FUNLOCK 

A file that has been locked with FLOCK in order to allow exclusive updating should be unlocked 
with FUNLOCK as soon as the update is complete. Dynamic locking and unlocking apply to files 
opened for this capability. In the aoptions parameter of FOPEN, bit 10 must be set to 1 in order 
to use either FLOCK or FUNLOCK. (For more discussion of dynamic locking and unlocking, 
refer to the FLOCK intrinsic description.) 

Suppose a file has been locked to allow update of a record. To unlock the file following completion 
of the update, use the call: 

FUNLOCK(FILNUM); 

When FUNLOCK is executed, all output written while the file was locked is transferred to the file 
so that other users have the most recent data. 



MAY 1981 4-91 



FUPDATE 

INTRINSIC NUMBER 4 

Updates the contents of a logical record in a KSAM file. 

IV LA JV 
W-l'DA.TVAfilcnum.ttirf'Kl.lcount); 

The FUPDATE intrinsic can be used to update a logical record in a KSAM file. The entire record 
including primary and any alternate keys can be updated with FUPDATE. The record to be updated 
is the record last referenced by the intrinsics FREAD, FREADBYKEY, FFINDBYKEY, or FPOINT. 
The new values for the record are moved from the user's stack into this record. The file containing 
this record must have been opened with the aoption parameter of FOPEN set to update access. 
FUPDATE can be used to update both fixed-length and variable-length records. FUPDATE can be 
used to modify key values or to change record size, but if key values or the record size are changed, 
the update operation causes the entire record to be deleted and then rewritten. After an update, a 
subsequent call to FREAD will read the next record in ascending key sequence after the record just 
written. 

FUPDATE checks only the logical record pointer, not the chronological pointer, in order to de- 
termine which record to update. Therefore, if you want to update a record based on its chronologi- 
cal position, precede the call to FUPDATE by a call to FPOINT. FPOINT locates the record by its 
record number and sets the logical, as well as the chronological, pointer. If you try to locate a record 
for FUPDATE by calling FREADDIR or FREADC, which only set the chronological pointer, the 
wrong record will be updated. 

If the file was opened for shared access (aoptions bits 8,9 = 11), then you must call FLOCK to lock 
the- file before calling FUPDATE. Note that the file must also have been opened with dynamic lock- 
ing allowed (aoptions bit 10 = 1). 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be updated. 

target logical array (required) 

Contains the record to be written in the updating. 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be written from 
the record. If this value is positive, it signifies words; if it is negative, 
it signifies bytes. If tcount is less than the recsize parameter associated 
with the record, only the first tcount bytes or words are written. 

CONDITION CODES 

CCE Request granted. 

CCG An end-of-file condition was encountered during updating. 

CCL Request denied because of an error, such as tcount exceeds the record 

size defined for the KSAM file; or tcount does not include all the keys; 
or a disc input/output error. 
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SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FUPDATE 

In order to update a record in a KSAM file, you must open the file for update. This access mode 
is specified by setting bits 12 through 15 of the FOPEN aoptions parameter to the octal value 5 
(binary value 0101). You must then access the record to be updated. Normally, you would read 
the record with one of the read intrinsics and then modify the record just read. 

The record to be updated by FUPDATE is the last record accessed. FUPDATE writes the contents 
of a user buffer area {target) over the existing contents of the last record accessed. The record 
written by FUPDATE must contain all the key values expected by the file. If only a portion of 
the record is specified by a tcount parameter less than the original record size, then this portion 
must contain all primary and alternate key values or a CCL condition is returned and the update 
does not take place. 

The example in figure 4-13 shows an update of an alternate key, the telephone number located in 
bytes 21 through 28 of the record. In order to locate the record to be updated, FREADBYKEY 
is executed before FUPDATE. The data input through the standard input device contains the 
key location and key value values for FREADBYKEY as well as the new value for the update: 



byte 



1 



*, 



keylocation 
(starting byte) 



21 



name 



22 



phone # 



keyvalue 
(primary key) 



29 



new value 
(alternate key) 



Note that bytes are numbered from zero in the standard input or output device, but bytes in the 
KSAM record are numbered starting from 1 for the keylocation parameter. 

SHARED ACCESS. When access is shared, it is essential to lock the file with a call to FLOCK be- 
fore rewriting any records. After the update, you should unlock the file with FUNLOCK. To make 
sure you are updating the correct record, include both the intrinsic that locates the record and 
FUPDATE between the same pair of FLOCK and FUNLOCK intrinsics. 
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For example, suppose you use FREADBYKEY to examine the record to be updated, you should 
lock the file before calling the intrinsic that locates the record to be updated and unlock if after 
the update: 

FLOCK 

FREADBYKEY (or FFINDBYKEY)- locate record to be updated 



FUPDATE- update record 

FUNLOCK- all key buffers, data buffers and control information written to disc 

If you perform operations on a record between locating it and updating it, and you do not want 
to lock the file during this process (between the read and the update), then you can use the fol- 
lowing code sequence : 

FLOCK 

FREADBYKEY (or FFINDBYKEY)- locate record 

FUNLOCK 

. -. while you decide whether to update record, 

other users can modify or delete it 



(decide to update) 
FLOCK 

FREADBYKEY (or FFINDBYKEY)- reread record 

FUPDATE 
FUNLOCK 

UPDATING RECORDS WITH DUPLICATE KEYS. If you want to sequentially update all the 
records in a chain of records with duplicate keys, locate the first record in the chain with FFIND- 
BYKEY, FREADBYKEY, or FPOINT. Then call FUPDATE to modify this record. If no key value 
(the selected key or any other) is modified, subsequent calls to FUPDATE will modify the next se- 
quential records in the chain of records with duplicate keys. If, however, any key has been changed, 
the modified key is written to the end of the chain and the next sequential record is one with the 
next higher key value. In this case, to update all records with duplicate keys, precede each call to 
FUPDATE with a call to FFINDBYKEY, FREADBYKEY, or FPOINT to position to the begin- 
ning of the chain. 

If you are in the middle of a duplicate key chain and FUPDATE modifies a key value, you can 
position back to the next duplicate key in the chain with the following sequence of calls: 

FSPACE(FILNUM,1);- position to next sequential record 

FGETINFO(FILNUM, ,,,,,,, ,RECPTR);- retrieve current record number 

FSPACE(FILNUM,-l);-i backspace to current record 

FUPDATE(FILNUM,OUTPUT,-72); modify key, positioning to end of key chain 



FPOINT(FILNUM,RECPTR);- position to next duplicate key using record number 

retrieved by FGETINFO 

Note that if the KSAM file has fixed-length records or if the updated record is the same size as the 
old record, the space in the data file is reused. Otherwise, the updated record is written to the end 
of the data file. 
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SCONTROL MMN»JEXAMP18 




<<D»»<«i>««««<i««»«<«>t<«»«««««*tta<««««iit«<i«»»««t«««««««» 


<<» 


*>> 


<<» EXAMPLE 8 


•>> 


<<• UPDATE A RECORD IN A KSAM FILE 


»>> 


<<» 


*>> 


<<aoa» «o a«oe«oo««e«>«»««ooao««<>o«»aoae«««ae<>o«ceooo<><'«««<>>> 


iNTfeGER FILNUMi 




INTtSER EffPORCODEl 




INTEGER -. IENOTHI 




SYTfc ArRAy FILNAME(0l9) I*"JEXAmfTL m , 




ARRAY MESSAGE (0: se ^ 1 




ARRAY .-'■ '' INPUT <0I39M .-.■.. :" '■ '' " ..:. 




ARRAY OUTPUT t*> ■ INPUT | 




BYTE ARRAY OUTPUTB < • ) «OUTPUT I 




BYTE ARRAY INFO (0I35| 1 




«RR'r !NFO«|»|»INFOI 




BYTE ArRAy KEYVAL^E(*)»INF0»£J « 




INTEGER "^ : : KE YLOC A T I ON 1 




INTRINSIC FOPFN.rCLOSE.FUPDATEifPEADeYKEY.tJt AD, PR I NT , 




B IN ARY.FCHECK.FERRMSGf TERMINATE! 




<<««•»»•«««••«»••«•««••••«>> 




<<• OPEN THE KSAM FILE »>> 




<<«»»»««»<»•«*«««•»«»•»»«««>> 




FILNUMJ3F PEN|FILNAME.3,5) » <<OPFN THE KS4M FILE FOR (JPDATE>> 


IF FILNUMsO 




THEN BEGIN <<CANNOT OPEN KSAM FILE>> 




MOVE MpsSAGEI ■"CANNOT OPEN KSAM FILE''I 




PRINT(MESSA9E.»21iO) 1 




FChECK (FILNUM.ERRORCODE) 1 <<GET ERROR NUMBER>> 




FERRMSGlERRORCODE, MESSAGE, LENGTH) |<<CONVERT TO STRING>> 


PRINT(MESSAGE, -LENGTH, 0> 1 <<PRINTOUT ERROR MesSAGE>> 


TERMINATEl 




ENOI 




<<•«»*»«•»«««««««««••»•««*•• •»•»«••««»«•»•»»«««••>> 




<<» READ IN KEYVALUE AND KEYLOCATION INFOMATlON •>> 




<<••••«««««••«»• ••••••••••»••«••«•»« •««••«»«»»»««>> 




Lit 




REA0<InF0w,-36) 1 




IF > 




THEN BEGIN 




FCLOSE (FILNUM.0,011 <<CLOsE THE KSAM FlLE>> 




IF <> THEN 




BEGIN 




MOVE MESSAGE! ■••CANNOT CLOSE THE KSAM FILE" I 




PRINT (MESSAGEi-26,0) 1 




FCHECK(FILNUM,ERR0RCO0E) | <<3ET ERROR NUMBER» 


FFRRMSGIERRORCODE, MESSAGE, LENGTH) |<<C0NV£RT To 


STRING» 


PRINT(MESSAGE, -LENGTH, 0) | <<PRINT0UT ERROR 


MESSAGE>> 


ENDI 




TERMINATEt 




ENDI 




IF < 




THEN BEGIN 




MOVE M(rsSAGE»»"ERROR OCCURRED WHILE READING INPUT" 


1 



Figure 4-13. FUPDATE Example 
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PRINT ( MESSAGE, «34,0>| 

TERMINATE! 
END | 
PRINT ;if*F0W»-36»Q) | «TEST RFftD» 
KEYLOCATION|«BJNARY(INFO,2) | <<CONVE"T FROM ASCII TO BINARV>> 

<<• REAO KSAm ACCORDING TO KEYVALUE AMD KEYLOCATION •» 

FREADBVKEV(FILNUM, INPUT, -72, KEVVALUE, KEYLOCA< I«N> l"'*" 
IF <> 

THEN BEGIN «ERROR OCCURRED IN FREADBYKEY» 

MOVE MESSAGE «»"ERROR OCCURRED IN FREaDBYKEY"! 
PRINT(MESSAGE,-28,0) I 

FCHECK<FlLNUM,ERRORCODE> f <<0ET ERROR NUMB£R>> 
FERRMSfi (ERRORCODE, MESSAGE, LENGTH) »<<C0NVERT TO STrINg>> 
PRlNTtMESSAGE, -LENGTH, 0) I <<PRINTOUT ERROR M EsSAGE>> 
GO TO LI I 
END | 

«• UPDATE THE RECORD JUST READ •>> 

««»m,e,«j„„ t ,, M „„„„„ ,„„ loM# , (|j(0|#a>> 

"'- -"- 3UTPJJTB ( 20 I I ■ INFO 1 22 J , ( 3 M 
F^P; I TE«F ...v ■*, 3UTPUT.-T2 } 
IF<> 

THEN BEGIN 

MOVE MFSSAGEja"ERROR OCCURRED DURING UPDATE"| 
PRlNTlMESSAGE»-28,0) | 

^CHECK<FILNUM, ERRORCODE) I <<GET ERROR NUM8ER>> 
FERRMSB(ERR0RCODE,MESSAGE,LENGTH) |<<cONVERT TO STPING>> 
PRINT(MESSASE, -LENGTH, 0>* <<PRINTOUT ERROR MEsSAGE>> 
TERMINATEl 
END I 

<<* print the record just updated •>> 

print(output,-72,0) i 

<<» go Back to get another record •>> 

GO TO LlJ 
END J 



Output from Program Execution: 

read from $STDIN 



/ 



.updated record 



OIWHITE GORDON 429.2498 

Wt-ITE GORDON 428-2498 43*0 ASH8Y AVE,'*' BE&kF.fy rA 91234 

01EC<STEIN LEO 263-2*64 

Eckstein leo 263-24*4 S30 3 stevens creek Santa clara ca, 95050 



Figure 4-13. FUPDATE Example (continued) 
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INTRINSIC NUMBER 3 



Write a logical record from the user's stack to a KSAM file. 

i WRITE / .■;■- um :, rg t,tcoi it < Urol); 

The FWRITE intrinsic writes a logical record from the user's stack to the KSAM file. The record 
contents are contained in the array target in the user's program and include all key values. 
FWRITE uses the primary key value to update the key file so that the new record is in sequence 
by primary key value. Any alternate keys are also entered into their appropriate positions in the 
key file. No separate key specification is required since all the key values are contained in the 
record to be written. 

Following execution of FWRITE, the logical record pointer is positioned at the next sequential 
record in key sequence or at the end-of-file if the record is the last in sequence. The particular 
key is the current key being used when FWRITE is called. 

If sequential processing was specified for the file in the flagword of ksamparam when the file was 
opened by FOPEN, then the records must be written in ascending order by primary key. If dupli- 
cate keys are not allowed, any record with a key duplicating a key in an existing record is not 
written and a CCL condition code is returned. 

When the physical bounds of either the data file or the key file prevent further writing (all allowable 
extents are filled), an end-of-file condition code (CCG) is returned to the user's program. 

If the file was opened for shared access (aoptions bits 8,9 = 11), then you must dynamically lock 
the file with FLOCK before calling FWRITE. Note that the file must also have been opened for 
dynamic locking (aoptions bit 10 = 1). 

PARAMETERS 

filenum integer by value (required) 

A word identifier supplying the file number of the file to be written on. 

target logical array (required) 

Contains the record to be written. 

tcount integer by value (required) 

An integer specifying the number of words or bytes to be written to the 
record. If this value is positive, it signifies words; if it is negative, it 
signifies bytes; if it is zero, no transfer occurs. If tcount is less than the 
recsize parameter associated with the record, only the first tcount words 
or bytes are written. 

If tcount is larger than the recsize value, the write request is refused and 
condition code CCL is returned. 

control logical by value (required) 

A logical value representing a carriage control code. This parameter 
has no meaning for KSAM files but must be included for compatibility. 
Whatever value is specified will be ignored. 
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CONDITION CODES 

CCE Request granted. 

CCG The physical bounds of the file prevented further writing; all disc 

extents are filled. 

CCL Request denied because an error occurred, such as: an input/output 

error occurred; a duplicate key value occurred when duplicates are not 
allowed; tcount does not include all keys; or sequential processing was 
specified in the flagword of ksamparam in FOPEN and the primary key 
is not the next in ascending order. 

SPECIAL CONSIDERATIONS 

Split stack calls permitted. 

USING FWRITE 

The FWRITE intrinsic writes records from an array in your program to a KSAM file. All the key 
information is contained in this target array. The record is written to the data file and the keyfile 
is updated to reflect the primary key and any alternate keys in the new record. 

Depending on how the file was opened, you can write records at random regardless of primary key 
order, or you may be constrained to write records in sequential order by primary key value The 
examples in this manual use the file JEXAMFIL that is created for writing at random. If you refer 
to figure 4-5, the flagword of the ksamparam parameter is set to the binary value 000000000000001 
Bit 14, indicating that record numbers start with 1, is the only bit set. If bit 13 had also been set 
to 1 then all records written to the file would have to be in ascending order by primary key value. 
In such a case, the chronological order of records and the sequential order would be the same. 

When you write a record to a KSAM file, FWRITE either overwrites any records previously written 
to the file or else writes new records following existing records. The choice is made when you open 
the file. If you set bits 12 through 15 of the aoptions parameter of FOPEN to the binary value 
0001 (octal or decimal 1), then all records written to the file before this open are deleted and 
FWRITE writes records to a cleared file. If you set bits 12 through 15 of aoptions to 0010 or 0011 
(octal or decimal 2 or 3), then any previously written data is saved. The example in figure 4-14 
deletes any data written to file JEXAMFIL before it was opened. The file will have no data other 
than that written by this program. If, after closing the file, you want to open it to write more data 
without deleting existing data, then you must set the aoptions access type (bits 12-15) to 0010 or 

SHARED ACCESS. When access is shared, it is essential that you lock the file before writing new 
records. This means opening the file with dynamic locking allowed and calling FLOCK before call- 
ing FWRITE. You should also unlock the file with FUNLOCK after writing the records. 
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$CONTROL MAIN.EXAMPLE9 

<<• •>> 

<<» EXAMPLE 9 •>> 

<<* WRITE TO EXISTING KSAM FILE »>> 

<<• •>> 

<<««a»«»ao«aa««aa«»«»«a<t«i>a««*««««««ao«»«««»a«««»««***#*«tt»>> 

INTEGER FIUNUMI 

INTEGER EpRORCOOEl 

INTEGER LFNGTHI 

BVTE ARRAy FILNAMEI0J9) l«»JEXAMFIL "I 

ARRAY . MESSASE (0135) I 

ARRAY ' . I N? UT ( I 39 ! I . ■'■■■ 

ARRAY OUTPUT (*)«INPUTI 

INTRINSIC FOPENiFCLOSE,FWRlTE,READ,PRlNT,FCHECK,FERRMSGl 

INTRINSIC TEBMINATEI 

<<« OPEN THE KSAM FILE •>> 
««»<«i«<i«i»itii<«tt l ««>«» 

FlLM*M|«FoPEN(FILNAMEi3,P) I <<OPE^ »ILE FOR WRITE>> 

IF FILNUM.O 

THEN BEGIN <<CANNOT OPEN KSAM FILE>> 

MOVE MESSAGEI»"CANNOT OPEN KSAM FILE»I 

PRINT(MESSA3E,-21 f 0) I 

FCHECK(FILNUM,ERRORCODE> I <<GET FRROR NUMBE H >> 

FERRMSg(ERRORCODE,MESSAGE,LENGTH) |<<cONVERT TO STRING>> 

PRINTIMESSA3E, -LENGTH, 0) I <<PRINTOUT ERROR MEsSAQE>> 
TERMINATE; 
END) 

<<• READ DATA FROM SSTDIN DEVICE •>> 

LH 

READ ( INPUT, -72) I <<"EAD ONE RECORD FROM $STDlN>> 

IF > 

THEN BEGIN <<END OF FILE ON *STDIN>> 

FCLOSE(FILNUM,l ,0) I <<CLOSE THE KSAM FILE>> 

IF <> THEN 

begin <<cann0t close the ksam file>> 
move message! ""Cannot close the ksam file'm 

PRlNT(MESSAGE,-29,0) | 

FChECK(FILNUM,ERrORCO0E| I <<«ET ERROR NUMgER>> 
FERRMSG(ERRORCODE, MESSAGE, LENGTH) |<<CONVERT To STRING>> 
PRINTlMESSAGE, -LENGTH, 01 | <<pRINTOUT ERROR MESSAGE» 
ENDI 
TERMINATEI 
END) 

IF < 

THEN BEGIN 

MO V E MESSAGE I s"ERROR OCCURRED WHILE READING INPUT"! 

PRlNT(MESSAGE,-3*>0) I 

TERMINATE! 
END» 
PRINT(OUTPUT,.72,0) 1 <<ECHO CH£CK>> 

<<« WRITE THE DATA JUST READ TO THE KSAM FILE •>> 
<<#««» a *» o ae «s a « ® » ft »»«««»«»« <n> ***»»# « #«^«« e « o» o «»»> > 

FW«ITE(FlLNUM (0 oTPuT,-T2,0l I 
IF <> 

THEN BEGIN <<ERROR OCCURRED WHILE WRITING KSAM>> 

MOVE MESSAGEi*"ERROP OCCURRED WHILE WRITING KSA* FILE"! 
PRlNT(MESSAGE,-3a,0) I 

FCHECK (FlLNUM,ERRORCODE) ! <<GET ERROR NUMBER>> 
FErRmSg (ERRORCODE, MESSAGE, LENGTH) |<<C0NVE"T TO STPING>> 
PRINTIMESSAGE, -LENGTH, 0) I <<PRINT0UT ERROR ME S sAGE>> 
TERMINATE) 
EnO| 

<<» go Back to get another record •>> 

<<««aae«ooo»<>e««aa»«e**»«»««aaoe<i«a««>> 

GO TO Ll I 
ENDI 



Figure 4-14. FWRITE Example 
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FWRITEDIR 

INTRINSIC NUMBER 8 

Writes a specific logical record from the user's stack to a disc file. 

NOTE 

This intrinsic may not be used for KSAM files. If called for a file 
created as a KSAM file, the intrinsic returns a CCL condition code. 



4-100 



FWRITELABEL 

INTRINSIC NUMBER 20 



Writes a user file label. 



IV LA IV IV 0-V 

FWR1TELAK1 L( .'■•■ iiu .:.■■■.• Uou nt/iabelid) 

The FWRITELABEL intrinsic writes a user-defined label onto a disc file. This intrinsic overwrites 
old user labels. 



PARAMETERS 

filenum 

target 
tcount 



labelid 



integer by value (required) 

A word identifier specifying the file number of the file to which the 

label is to be written. 

logical array (required) 

Contains the label to be written to the disc file. 

integer by value (optional) 

An integer specifying the number of words to be transferred from the 

array. 

Default: 128 words. 

integer by value (optional) 

An integer specifying the number of the label to be written. The first 

label is 0. 

Default: A default value of is assigned. 



CONDITION CODES 

CCE Request granted 

CCG 



CCL 



Request denied because the calling process attempted to write a label 
beyond the limit specified in FOPEN when the file was opened. 

Request denied because an error occurred. 



SPECIAL CONSIDERATIONS 

Split stack calls permitted. 
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FWRITELABEL 

USING FWRITELABEL 

You can write your own labels to a KSAM file with the FWRITELABEL intrinsic. Such labels are 
useful to hold information related to the file but not part of it. For example, you might use a label 
to contain the date and time of the last update to the file. 

The number of labels that are allowed to be written to any file must be specified in the userlabels 
parameter of the FOPEN intrinsic when the file was created. If an attempt is made to write more 
labels than are specified for the file at creation, a CCG condition is returned. 

In order to write labels, as with any other write request, the file must be opened for write access. 
This means that the aoptions parameter of FOPEN must be set to one of the following: 

bits 12:4 = 0001 (octal 1) >j 

0010 (octal 2) - write only access 

0011 (octal 3) ) 

= 0100 (octal 4) input/output access 

= 0101 (octal 5) -* update access 

Suppose file KDATA has been created as follows: 

KFILNUM:=FOPEN(KDATA,%4004,4, , , , 2); 

new KSAM file,/ \ ^number of labels 

ASCII coded input/output access 

Then a total of two labels, each with a maximum of 128 words, can be written to this file with 
FWRITELABEL. To write a second label consisting of 60 words stored in the array LABELBUF, 
use the following call: 

FWRITELABEL(KFILNUM,LABELBUF,60,1); 
Note that label numbering starts with zero, so the second label is identified by the number 1. 
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HP32208 

INTRINSIC NUMBER 308 



Returns current version, update, and fix level of KSAM/3000. 



D 
version:=H?32208 



The double word result returned by HP32208 contains the version number in ASCII, the update 
number in binary, and the fix-level number in binary of the KSAM/3000 version currently in use. 

FUNCTIONAL RETURN 

version Double word returned by HP32208 in the form: 

7 8 15 

word 1 



Version, in ASCII 



Update #, in binary 



Fix-level #, in binary 



word 2 



CONDITION CODES 

Condition codes are not affected by execution of this intrinsic. 

USING HP32208 

You may call this intrinsic in order to get the current version, update, and fix numbers of the 
KSAM/3000 that is currently being used. The intrinsic FGETKEYINFO returns the version, up- 
date, and fix number of a KSAM file at the time the file is created (refer to words 16/17 of the 
ksamcontrol parameter, table 4-4). The version, update, and fix number of a KSAM file at 
creation is also returned by the VERIFY command (refer to section II). You can call HP32208 
to get the KSAM version you are using in order to compare it with the version at file creation of a 
file you are accessing. 

Another reason for calling HP32208 is if you want to convert the version, update, and fix numbers 
to display values so they can be listed for documentation purposes. 
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USING KSAM FILES IN FORTRAN 

PROGRAMS 



SECTION 



OVERVIEW 



The FORTRAN language has no input/output statements that can be used to access or create a 
KSAM file directly. In order to reference KSAM files for input or output, the FORTRAN 
programmer can choose between using MPE file system intrinsics (as described in section IV) or 
using COBOL procedures (described in section III). He can create a KSAM file with the 
KSAMUTIL utility program (described in section II) or with a call to the FOPEN intrinsic, but 
not with a COBOL procedure. 

If you are programming in FORTRAN, you can use the CALL statement to call any of the 
COBOL procedures or any of the file system intrinsics that access KSAM files. In order to 
determine which to use, you should refer to table 3-1 for a list of the COBOL procedures that 
provide KSAM interface and to table 4-1 for a similar list of the file system intrinsics used for 
KSAM interface. You will note that there are differences in the functions provided. 



Since the COBOL procedures are described in detail in section III and the file system intrinsics 
are described in detail in section IV, these descriptions are not repeated here. This section merely 
describes how to call the COBOL procedures or the file system intrinsics, and provides examples 
of file creation and access along with brief commentaries. 



5-1 



CALLING FILE SYSTEM INTRINSICS 

To the FORTRAN user, some of the file system intrinsics are treated as functions and others as 
subroutines. A function is called implicitly by being referenced in a FORTRAN statement. A 
subroutine is called explicitly with the FORTRAN CALL statement. A further distinction is that 
a function can return a value to the calling program as a functional return, whereas a subroutine 
can return values only through the parameters (arguments) specified in the call. 

To illustrate, the FOPEN intrinsic is called as a function: 

FILNUM=FOPEN(FILENAME,%4004L,%101L,-72,DEVICE,KSAMPARAM,,10,,100J) 

When this statement is executed, a value is returned to the integer variable FILNUM. Note that 
the word CALL is not used. On the other hand, the FWRITE intrinsic is a subroutine that must be 
called with the CALL statement: 

CALLFWRITE(FILNUM,OUTPUT,-72,%OL) 

In order to determine quickly which is which, look up the intrinsic definition in section III; if it 
has a functional return it should be called as a function, if not it should be called as a subroutine. 

MPE/3000 system intrinsics differ from FORTRAN/3000 language procedures: System 
intrinsics can have optional parameters (arguments) whereas all parameters must be specified in 
a call to a FORTRAN procedure. Another difference is that parameters can be passed by value 
to a system intrinsic but they must be passed by reference to a FORTRAN procedure. To pass 
a parameter by value, use the literal value as a parameter (the parameter -72 in the FOPEN call 
above); to pass by reference, the value is assigned to a parameter specified as a variable or array 
name (FILENAME in the FOPEN call). 

In order to take advantage of the capabilities of the system intrinsics, you should declare the 
names of any intrinsics you plan to use in a SYSTEM INTRINSIC statement. This statement 
must appear as one of the declaration statements that precede executable statements in a 
FORTRAN/3000 program. For example, if you plan to call FOPEN, FCLOSE, FWRITE, and 
FCHECK then these intrinsics should be declared in the statement: 

SYSTEM INTRINSIC FOPEN,FCLOSE,FWRITE,FCHECK 

Declared in this way, you can then omit optional parameters from the call and pass parameters 
by value. If you do not declare the intrinsics in a SYSTEM INTRINSIC call, then a function call 
such as that illustrated above for FOPEN would generate an error because it omits some para- 
meters and passes others by value. 
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CALLING COBOL PROCEDURES 

Like the FORTRAN/3000 procedures, COBOL/3000 procedures do not allow you to omit any 
parameters from the parameter list or to pass parameters by value. Thus no special provisions 
need be made in order to call COBOL procedures from a FORTRAN program. Since the COBOL 
procedure call differs in format from the FORTRAN procedure call, you must translate from the 
COBOL format when calling a COBOL procedure in a FORTRAN program. The translation 
is simple: 

CALL "CKOPEN" USING filetable , status. * COBOL format 

t \ / 

procedure parameters 

name 

I 

CALL CKOPEN (filetable, status) -* FORTRAN format 




5-3 



CREATING A KSAM FILE WITH A CALL 
TO FOPEN 

A KSAM file can be created with the >BUILD command of the KSAMUTIL program or it can 
be created programmatically through a call to the file system intrinsic FOPEN. Figure 5-1 
contains a FORTRAN program that uses the intrinsic FOPEN to create and open a file, and the 
intrinsic FWRITE to write to the open file. It checks for errors with the FCHECK and FERRMSG 
intrinsics, and closes the file with a call to FCLOSE. 

The file is named FEXAMFIL and the associated key file is named FKEYFILE. Two keys are 
used, a primary key of 20 characters starting in byte 1 of each data record, and an alternate key 
of eight characters starting in byte 21 of the data record. The primary key contains a name, the 
alternate key a phone number (refer to the input data in figure 5-1). 

DEFINING KSAMPARAM 

The parameter ksamparam describes the key file in an array that contains many different types 
of data (refer to table 4-7). Because the data differs, the EQUIVALENCE statement is used to 
equate the word-array KSAMPARAMA to the byte-array KSAMPARAM to the double-word-array 
KSAMPARAMD. The keyfile name is in the first eight bytes and this is equivalenced to the 
beginning of the array. The key device is defined in word 7 of KSAMPARAMA, and the key 
descriptions begin in word 18. 



The flag word (word 17) has the octal value 2. This means that only bit 14 is set to 1. 
flagword defines the following options for the KSAM file: 



The 



bit 13 = file is permanently saved in system directory 

bit 14 = 1 record numbers in file start with 1, not zero 

bit 15 = records can be written in random order 

If you compare this ksamparam definition to that in the SPL sample program (figure 4-5), you 
will note that the index values into the array differ. This is because, SPL arrays begin numbering 
with zero whereas FORTRAN arrays begin numbering with one. 

CALLING FOPEN 

In the FOPEN call, the first parameter is the KSAM file name that identifies the data file and 
the KSAM file as a whole. The second parameter specifies the file options (f options) parameter 
as octal 4004: 



01234567 


8 9 10 11 12 13 14 15 








10 











10 








4 










4 



binary 
octal 



This defines the following file options: 

New KSAM file (bit 4=1) 

Allow :FILE (bit 5=0) 

Fixed- Length Records (bits 8,9=00) 

ASCII code (bit 13=1) 

New file (bits 14,15=00) 
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„ J- device 



Ctt«tt»ett«tt0»«»ee«««««e«e«tt««««««««tt«««#»»«*««««e.0««««»«»»« 

c * 

C EXAMPLE 1 * 

C BUILD A KSAM FILE * 

C * 

SvSTEM IwT«INSiC FOPEn.FCLOSE.FwRITE.FERRm^G.FChECk 

integer ksamparama(<;6) 

INTEGER KEyDEScRTpTI0N(8> 

CHARACTER KSAMPARAMI52) 

INTEGER** kSAmPARaMO(13) 

CHARACTtRttB KEYFltENAME 

CHARACTtRol7 KEYDEVICE 

EOUlVALtNCE (KSAMdaRama,KSAMPaRaM,K^AMPaRaMD,«EyFILENAME) 

EQUIVALENCE < K£ YDE V I CE , *S AMP AR AM A ( 7 ) ) 

EQUIVALENCE < KSA M PARAMA ( 18 ) , KEYDESCR IPTION) 

INTEGER FILNUM 

INTEGER LENGTH 

CHARACTtR FILENA M E#10 

CHARACTER DEVlCE»tO 

CHA«ACTtRo72 INPUT 

LOGICAL OUTPUT (3*) 

CHARACTtH MESSAGE(7i2) 

LOGICAL MESSAGEW(?6) 

EQUIVALtNCE (MESSAGE, MESSAGE*) 

EQUIVALENCE < INPUT , OUTPUT ) 

data filenamE/"FExamfil "/- filename 

DATA UEVICE/"DISC "/ 

DATA Ke.YDEvICE/»OlSC 

DATA KEYFILtNAME/"FKEYFILE"/ 

data ksampahamd (3) /looJ/ -* file size 

DATA KSAMPARAMA (1*) /2/ -. flaglVOrd 

DATA KSAMPAWAMA(l7)/2/-« no. of keys 

DATA KEYDESCRIPTION/St^/I ,13/20] , 1 , %C 1 /O , 15/4 1 , , \ Hey 

I M4/1.12/ 8] ,21 »%r 1/0,15/45,0// descriptions 

c »«<»»»**«»«*»«»<»«*»««««»«»«»«»«»«**«»»******************* 

C 

r OPEN THE <SAM FILE * 

C 

r»»»»«o<» #«#»*«*»«»»»*«*»*»*»<»*•»««*•******** ************* 

F iLNUMsf OPEN ( FlLFN»;ME,*4 0^L,*l01L,-Tg,DEV ICE, KS AMP ARAM, 

1 , 10, , 100 J) 

IF {FILNUM .EQ. 0) GO TO 400 

(»•»»»♦***»•*»*»*•*•*»»•#***»************************** 

C 

r REAH DATA FROM *STDIN » 

C * 

c »»o#»#»<nt««»»»« »*•#»•*••«••»•••****•***•***** ******** 

20 READ (5,30O»EnD=30,ERH=40) INPUT 
r* «»*»««♦»**«*»««***»**»****************** ************* 

v.- # 

C WRITE THE DATA JuST READ TO THE KSAM FILE * 

C«hhhhhkhh»*«»»«<hh»»»# »*«*»»»« »*o»*** ******* ************* 
bo DISPLAY INPUT 

CALL F WR I TE (FILNUM, OUTPUT, -72 i *0L> 
IF (,CC.) 70,20,70 



Figure 5-1. Creating and Writing to KSAM File in FORTRAN 
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c 
c 



# 

ERROR MFSSASE * 



C * 

7(. STOP "EHRQR OCCUPIED WHILE WRITING KSaM FILE" 
100 STOP "ENO OF JOP" 
30 CALL FCLOSE(FIlNUn;,0,0) 

IF (.^C.) 33,ioO»?3 
33 STOP "Cmi\j NOT CLOSE THE KSAM FILE" 
<»0 STOP "EH«OR OCCURRED WHILE READING INPUT" 
<*00 CALL FCHECK(FILNUM,IERRNUM) 

CALL F"Eh<WMSG( I ERPNUM, MESS AGEW, LENGTH) 
WRITE (6 i 20 0) (MESSAGE (I ) , 1 = 1, LENGTH) 
STOP "ON NOT OPEN KSAM FILE" 
3O0 FORMAT (A72) 
200 FORMAT <1X,72A1 ) 
END 



Output from Program Execution: 

NCL^M .JACK 9?J-497b t}f,7 «fctU AVE, 

HCsH3A jut 227-d2i<» ijfin SAINT PETER CT, 

ECKSTEIN LtO 2M/-513/ S303 STEVENS CREEK 

CAhOIN ?1CK S7d-701« 1 1 1 (1 WOLFE ROAD 

PASBY Ll^OA 29=>-1187 TOWN n C\TRY VILLAGE 

StELY mcNKy 2^3-4^20 ij*<i LEuERTY ST. 

RC^E^tT GtRRY 2S9-S53S 1^3<,S TELEGRAPH A V E. 

TLnV;WW TV«rj 9b<*-fcft9H ??^^S EMERSON ST, 

WhITt GOROON 3*d-030l fcjSo ASHBY AVE. 

WE STEP FLbtw 2br-<fb9t» 12S* KlNGFIShEW ST, 

STOP ENn ot- J01< 



SUNNYVALE 
LOS ALTOS 

s»anta cLara 
cupertino 

Sam jose 

EL CERRITO 

BERKELEY 

OAKLAND 

8FPKELEY 

SUNNYVALE 



Figure 5-1. Creating and Writing to KSAM File in FORTRAN (continued) 



The next parameter defines the access options (aoptions) as the octal value 101: 



12 3 


4 5 6 


7 


8 9 10 11 


12 13 14 15 














1 








1 













1 







1 



binary 

octal 



This defines the following access options: 

KSAM access expected (bit 3=0) 

Exclusive access (bits 8,9=01) 

No dynamic locking (bit 10=0) 

Write only access (bits 12-15=0001) 
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A new file contains no information and is always opened for write access. Before accessing the file 
for reading or update, it must be reopened. Such an open specifies that the file is an old file in 
the foptions parameter. Depending on the type of access expected, aoptions can be omitted 
or can specify a particular access type. 

CREATING A KSAM FILE WITH KSAMUTIL 



Instead of using the file system intrinsic FOPEN to create the KSAM file, you can create the 
file with the >BUILD command of the KSAMUTIL program. Once created, the file can be 
opened with a call to FOPEN or CKOPEN. (Note that CKOPEN cannot be used to create a file.) 

The same file created in figure 5-1 with FOPEN could be created in KSAMUTIL as follows: 

t ^TIN KSAMHTiL.PTTB. ^YS 

> bttild fexamfil; r ?ec = -72 j hif.a^ci i j pev=di sc; di?c=1 w> & 
keyfile=fkeyfile;key=b, i , ??jkey=b.,jh , s;fipstpec = i 
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OPENING A KSAM FILE WITH A COBOL 
PROCEDURE 

The CKOPEN procedure requires two parameters: one is a table that identifies the file and 
specifies the type of access; the other is a two-byte item to which the status of the call is 
returned. When calling this procedure from a FORTRAN program, the filetable parameter must 
be defined as an eight-word array containing both integer and character values. 

Any item that is defined as COMPUTATIONAL or COMP in a COBOL program is declared as 
an INTEGER in a FORTRAN program when it contains four bytes or less. Thus, the following 
are equivalent: 

02 FILENUM PIC S9(4) COMP. COBOL description 

INTEGER FILENUM — FORTRAN description 

Any data items defined with a picture of X in COBOL would be declared as CHARACTER items 
in FORTRAN. Thus, the following are equivalent: 

02 FILENAME PIC X(8). *- COBOL description 

CHARACTER *8 FILENAME FORTRAN description 

Assuming that file FEXAMFIL has been created by the >BUILD command, the FORTRAN 
statements in figure 5-2 open that file for output only and sequential access. 



INTEGER FILETABLE(8) 

CHARACTER FILETABLC(16) 

INTEGER FILENUM 

CHARACTER*8 FILENAME 

CHARACTER*2 FSTAT 

INTEGER IOTYPE 

INTEGER AMODE 

INTEGER PREVOP 

EQUIVALENCE (IFSTAT,FSTAT) 

EQUIVALENCE (FILETABLE,FILETABLC,FILENUM) 

EQUIVALENCE (FILETABLC(3),FILENAME) 

EQUIVALENCE (FILETABLE(6),IOTYPE) 

EQUIVALENCE (FILETABLE(7),AMODE) 

EQUIVALENCE (FILETABLE(8),PREVOP) 

DATAFILENAME/"FEXAMFIL"/,PREVOP/0/ 

£***************************#************************************ 
C OPEN KSAM FILE FOR SEQUENTIAL INPUT * 

£**** ************************************************** ********** 

IOTYPE=l I/O type is output only 

AMODE=0 access mode is sequential 

CALL CKOPEN( FILET ABLE,IFST AT) 



Figure 5-2. Opening KSAM File with CKOPEN 
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WRITING TO A KSAM FILE 



Once a KSAM file has been created and opened for output access, you can write to the file with 
a call to FWRITE or a call to CKWRITE. You may choose to write records in primary key 
sequence and have that sequence checked. To do this, you can open the file for sequential 
access with CKOPEN or else call FOPEN with bit 13 of the flagword in ksamparam set to 1. If 
the sequence in which records are written doesn't matter, you can open the file for random 
access in COBOL or open the file by calling FOPEN with bit 13 of the ksamparam flagword 
cleared to zero. 

The example in figure 5-1 uses FWRITE to write records to the KSAM file in the order in which 
they are read from the standard input device; they are not written in primary key order. 

Since duplicate primary keys are never allowed by the COBOL KSAM procedures, you should 
use the file system intrinsics if you want to allow duplicate primary keys. Duplicate alternate 
keys are allowed by both the file system and COBOL if so specified when the file was created. 



5-9 



READING A KSAM FILE IN KEY ORDER 



PRIMARY KEY SEQUENCE 

Reading a file in primary key order requires no other preparation than to open the file (file 
system) or to open the file for sequential input (COBOL). In the file system, sequential logical 
read is the default and the aoptions parameter can be omitted from the FOPEN call. In a COBOL 
procedure, input type and sequential access are indicated by zero values in the appropriate words 
of the filetable table. 

Once opened for input, the file system FREAD intrinsic or the COBOL CKREAD procedure can 
be called to read the file in sequence by primary key. 

ALTERNATE KEY SEQUENCE 

To read a file in sequence by an alternate key, that alternate key must be specified in a call prior 
to the call to a read procedure or intrinsic. In COBOL, you would use a call to CKSTART; with 
the file system intrinsics you would use FFINDBYKEY. 

The example in figure 5-3 illustrates use of the file system intrinsics FREAD and FFINDBYKEY 
to read a KSAM file in sequence first by primary key and then by alternate key. 

RANDOM ORDER 

A particular record in the file can be selected for access according to the value of a key field in 
the record. This can be a primary or alternate key field. In COBOL, a call to CKREADBYKEY 
reads a record specified by the key value parameters. The file system uses the intrinsic 
FREADBYKEY for the same purpose. The main difference here is that the file must be opened 
for random access before calling the COBOL procedure; no distinction is made by the MPE 
file system between a file opened for sequential access and one opened for random access. 
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C EXAMPUc * 

r HtAD KSAM FILE SEQUENTIALLY * 

r *»»»#«»«#««»»»#»»»«»**»»*>*#»*»*******»* ************ 

SYSTEM INTRINSIC FOPEN , FCLOSE , FWR I Tt , FERRMSG , FCHECK 

SYSTEM INTRINSIC FREAD , FF I NDBYKE Y 

INTgGEK FILNUm 

CHARACTtR FlLENAMEoiO 

CHARACTER QUTPUT»72 

CHARACTtR MESSAGE (72) 

LOGICAL INPUT (36) 

LOGICAL ME.SSAGFWOM 

EQUIVALENCE ( MESSoGE , MESSAGE*) 

EQUIVALLNCE (OUTPUT, INPUT) 

CHARACTtR KfcYVAL*H 

DATA FILENAME/i'FEXAMFIL "/ 

DATA KEYVAL/"000-0000"/ 
r *«*««»«*«» »*«»»«»*»»«*»»«*»*»******* **************** 
r UPEN KSAM FILE FOR INPUT • 

C«*#«*»«*««»***«»******«**************************** 
FlLNUMsP0PEN(FILFNAME,J,7L) 

IF (FILNUM .EQ. fl > GO TO 200 
c ««»«HHH>*««««#««»«»**«»*o»**************** ********** 
c HEAD DATA FROM FILE IN • 

c SEQUENTIAL ORDER * 

c «»»*«»*#»»««*»««*»«««*«**************************** 
DISPLAY "PRINT RECORDS IN NOME ORDE K " 

20 IL£N«FHtAO(FILNUM, INPUT, -72) 

IF (.CO 300.30,35 
30 DISPLAY OUTPUT 
GO TO HO 
/.««««*»•«••««*«««*»»•**•****»*********************** 

;.' reao in sequence by alternate key • 

r #*»»«« ft******************************************** 
35 DiSPLAY MPKINT RECORDS IN PHONE « ORDER" 
CALL FF1NDBYKEY (FILNUM, KEYVAL, 21 »B,f) 
IF I.CCI <»Oo,<»0,*00 
40 ILEN»FRfcAD(FIUNUM,lNPUT»-72) 

IF (.CO 5oo,*5,50 
«f5 DISPUAY OUTPUT 
GO TO <*0 
c «»«»«««*«»*»»»»»**»»»»**»»*»*********************** 
c CLOSE FILE * 

<»«•««•«•»«»•*«»«*•*•»•»»**************•************* 
&0 CALL FCCOSE<FILNUM,0,0> 
IF (.CO 600f55,600 

5S STOP "END OF JOB" 
(.•••••••••••••••••ft* ••••••#•••• 

r ERROR MESSAGES * 

£••••«••••#•••«••»*»»*•«**•*»•»*•*•****•************ 

200 CALL FCHECK<FILNUM,IERRNUM) 

CALL FEHRMSGdERRNUM, MESSAGEW, LENGTH) 

WRlTEl6f250) (MESSAGE(I) il"l, LENGTH) 

STOP "CANNOT OPEN kSAM FILE" 
300 CALL FCMECK(FILNUM,IERRNUM) 

CALL FE«RMSG(IER R NUM, MESSAGEW, LENGTH) 

WRITE (6, 250) (MESSAGE(I) t I "X. LENGTH) 



Figure 5-3. Reading KSAM File in Key Sequence Using FORTRAN 
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^00 CALL FCHECK (FlLNUM.IERRNUM) 

CALL FEHHMSGt I ERRNUM, MESSAGE W, LENGTH J 

WRITE <6 t 250) (MESSaGE(I) , 1,1, LENGTH) 

STOP •' tRROR OCCURRED WHILE USING FlFINDBYKEY" 

300 CALL FCHECKIFILNUM, IERRNUM) 

CALL FE*RMSG< lERRNUM f MESSAGEW, LENGTH) 

WRITE <b .25 0) (MESSAGE ( I) , I s 1 , LENGTH) 

STOP "ERROR OCCURRED READING 8Y ALTERNATE KEY" 

600 CALL PCHECK (FiLNUM, IERRNgM) 

CALL FEWHMSGt IER R NU* i MESSAGE* , LEMGTH ) 
WRITE (6 ,250) (MESSAGE (I) , 1=1, LENGTH) 
STOP "CANNOT CLOSE FILE" 

25o FOR<AT( 1X,72A1 ) 
END 



Output from Program Execution: 



PRINT RECORDS IN 



CflwDIN 

ECKSTEIN 

HCS03A 

NCLAM 

p A38Y 

"C^E^T 

SEELY 

Tu«N;WR 

WESTrR 

WHIT 



PICK 

LED 

JOE 

JACK 

UNOA 

GERRY 

hENKy 

I VAN 

ELDER 

GORDON 



PRINT RECORUS in 



HCSODA 

Robert 

WESTER 

Eckstein 

seely 

Pasby 

WHITP 

Cardin 

NOLA^ 
TU-JNEWR 
STOP ENn 



JOE 

GERRY 

ELUER 

LEO 

HENRY 

LINDA 

RURDON 

RICK 

JACK 

I VAN 

OF JOS 



NamE OHUEr 
57B-7018 
2»7-5l37 
227-621'! 
923-4975 

295-U8? 
2^9-5535 
293-4220 
964-849B 
287-4598 
398-0301 

phone * ordei 

227-8214 
259-5535 
2B7-459B 
2B7-5137 
293-4220 
295-1187 

3*8-0301 
578-7018 
923-4975 
984-8<»98 



lllOO WOLFE ROAD 
5303 STEVENS CREEK 
11^0 SAINT PETER CT, 
967 PEEO AVE. 
TOWN fc, CNTRY VILLAGE 
123*5 TELEGRAPH AVE. 
1144 LEBERTY ST, 
2290b EMERSON ST. 
125ft KINGFISHER ST, 
435n ASHBY AVE, 
! 

HBO SAINT PETER CT. 
12345 TELEGRAPH AVE. 
1256 KINGFISHER ST. 
5303 STEVENS CREEK 
1144 LEBERTY ST. 
TOWN i. CNTRY VILLAGE 
435o ASHBY AVE. 
lllOO WOLFE ROAO 
967 REED AVE, 
22905 EMERSON ST. 



Cupertino 
Santa clara 
los altos 
Sunnyvale 
San jose 
berkeley 
el cerrito 
Oakland 
sunnyvale 
berkeley 

los altos 
berkeley 
sunnyvale 
santa clara 

EL CERRITO 
San josE 

berkeley 

cupertino 

Sunnyvale 

OAKLAND 



Figure 5-3. Reading KSAM File in Key Sequence Using FORTRAN (continued) 
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READING A KSAM FILE IN CHRONOLOGICAL 
ORDER 

The order in which records are physically written to a data file is called chronological order. 
This order is not necessarily the same as a sequence by key value although it may be. In particular, 
if the records were written by a COBOL procedure to a file opened for sequential access, then 
the chronological sequence and the primary key sequence are the same. If, however, these orders 
differ, then the file system provides an intrinsic that allows you to read a KSAM file in chrono- 
logical order. 

Figure 5-4 is a program that uses the intrinsic FREADC to read the records in the order they were 
stored in the file. 

Other file system intrinsics allow you to position the file to a particular record number in 
chronological order (FPOINT), to retrieve the current chronological record number (FGETINFO), 
and to read a record located by its chronological record number (FREADDIR). 

The COBOL procedures for KSAM interface do not provide the means to access records by 
chronological record number. 



C EXflM<=[_3 « 

C HtAD KSAM FjLE CHRONOLOGICALLY <t 

SYSTEM INTRINSIC FCiPEN , FCLOSE , FE^RMSG , F CHECK 

SYSTEM INTRINSIC FPEADC 

INTFGEN FILNUM 

CHARACTtW FlLENAMfftlO 

CHarACTLR OUTPUT«72 

CHARACTtR MENAGE (72) 

LOGICAL INPUT (36) 

LOGICAL MESSAGE'*' OM 

EQUIVALENCE (MESSAGE, MESSAGED) 

EUUlVALfcNCE I OUTPUT , INPUT ) 

DATA FILENAME/"FFx/iHFIL "/ 
f•»»o«»o«>o^^»»»»»»»*»«►»<»»»** *»****** 4, *' ,> * ,, * ***** ** c,, 
c OPEN KSAM FILE FOR INPUT « 

r^^»^^»^»^H^^t^^»^^» ,, «»»*»»^^«*•»*»•**»** ,M *"* <,<, *** * < ****** ft ' l, 

FlLNUM = COPEN(FrtLFNAME,S7L) 

IF (FILNUM ,EQ. 0) GO TO 200 

c *EAD DATA FROM FILE IN « 

C CHRONOLOGICAL ORDER • 

C» »»«#»»«(»»*#•«»»»»«*#»»»«»«»•»••»••***• »« ««»»*»**»* 

DISPLAY "PRINT HFCORDS IN CHRONOLOGICAL ORDER" 

2 I LENsFRt ADC (FILNUM, INPUT, -72) 

IF (.CC.) 300,30,50 
3u DISPLAY OUTPUT 
GO TO <i0 

c " CLOSE FILE " 

b0 CALL FCi-OSE (FILNUM, 0,0) 

IF (.CO 600,55,600 
S5 STOP "END OF JOB" 



Figure 5-4. Reading KSAM File in Chronological Sequence Using FORTRAN 
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C ERROR MESSAGES » 

200 CALL FCHECKiFlLNUM, IERRNUM) 

CALL FEHRMSGI I ERRNUM, MESS AGEW, LENGTH) 

WRITE (6,250) (MESSAGE (I) , I »1, LENGTH) 

STOP "CANNOT OPEN K3AM FILE" 
300 CALL FCHECK(FILNUM, IERRNUM) 

CALL FEHRMSG ( I ERRNUM, MESS AGE W, LENGTH) 

WRITE(6|250I (MESSAGEII) plsl, LENGTH! 

STOP "ERROR OCCURRED READING IN CHRONOLOGICAL ORDER" 
600 CALL FCHECKIFILNUM, IERRNUM) 

CALL FE*RMSGl I ER p NUM, MESS AGE W , LENGTH ) 

WRITE » b » 250) ( MESSAGE ( I) i 1=1 , LENGTH) 

STOP "Cannot CLOSE FILE" 
250 FORMAT! 1X.72A1 ) 

END 



Output from Program Execution: 

Ri-ill^T REclwuS I(M CHRONOLOGICAL ORoE'* 

9*7 PEED AVE. SUNNYVALE 

11«0 SAINT PETER CT. LQs ALTOS 

53"? STEVENS CREEK SANTA CLARA 

lllon WOLFE ROAO CUPERTjNO 

TOWN t, CNTHY VILLAGE SAN JOsE 
llfc/i LEBERTY ST, ( EL CERRITO 

12^5 TELEGRAPH AyE, BERKELEY 

??9(i?. EMERSON ST. OAKLANf) 

<»35ri flSrteY AVE. BERKELEY 

125*, KIN&FISHER ST. SUNNYVALE 

STOP ENn Oh JOb 



Figure 5-4. Reading KSAM File in Chronological Sequence Using FORTRAN (continued) 



NCL l ^ 


jmCK 


92J-0975 


HC5CTA 


juE 


227-H21* 


Eckstein 


LcU 


2U 7-5J37 


C A -JOIN 


hICk 


578-7016 


P A , * V 


i.INDA 


2S»-J-11U7 


SEM.Y 


HLNWY 


2*3-4220 


«C^E'T 


Gt-WRY 


2&9-S535 


TbK'JrWR 


T V An 


96<.-649B 


WI-ITr 


r.onuoN 


3*o-03ol 


"E iTiP 


rLUER 


287-4596 
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USING KSAM FILES IN 
BASIC PROGRAMS 



SECTION 



VI 



OVERVIEW 



KSAM files are accessed from BASIC programs through calls to a set of input-output procedures. 
These procedures allow you to open, write records to, read records from, update and delete 
records, position, lock, unlock, and close KSAM files. (Refer to table 6-1 for a list of the 
procedures and their associated functions.) 

A KSAM file must already exist before it can be accessed from a BASIC program. It is usually 
created with the KSAMUTIL program BUILD command. (Refer to section II for a description of 
BUILD.) The BASIC procedures for accessing KSAM files do not provide a means to create a 
KSAM file. 

NOTE 

The BASIC procedures to access KSAM files perform input-output 
activities differently from the BASIC input-output commands. The 
KSAM procedures read and write records in their entirety. Once 
part of a record has been read or written by one of the KSAM file 
access procedures, the entire record has, in actuality, been read or 
written. A subsequent call will access another record. 
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CALLING A KSAM PROCEDURE 

The KSAM interface procedures are called from a BASIC program with a CALL statement of 
the following general form: 

statement label CALL procedure name (filenumber, status [ , parameterlist ] ) 

Where 

statement label is the number of the statement in the program. 

procedure name identifies the KSAM access procedure to which control is 

transferred. (Refer to table 6-1 for a complete list of the procedure 
names.) 

filenumber is a numeric variable whose value identifies an open KSAM file. 

This parameter must be present. Its value is assigned by KSAM/ 3000 
when the file is opened and must not be changed until the file is 
closed. 

status is a 4-character string variable to which a code is returned that 

indicates whether the current operation was successful or not, and 
if not, the reason for failure. 

parameterlist is a set of one or more parameters that, if present, further define 

input-output operations on this file. 

The first two parameters, filenumber and status are included in every KSAM procedure call, 
except BKERROR and BKVERSION. The parameters in parameterlist depend on the procedure 
in which they are used. Some parameterlist parameters are optional and, if omitted, default 
values are assigned by KSAM. Such parameters are indicated by brackets in the procedure call 
format. The required parameters filenumber and status are both variables, the first numeric, the 
second string. Other parameters are either variables or expressions. Expressions being either 
variables, constants, or a combination of both. The data type of the parameter depends on its 
definition in the procedure. The procedure call formats specify the data type of each parameter. 

Depending on the procedure, certain variables can be assigned values as a result of executing the 
procedure. The procedure itself is never assigned a value (unlike a function, which may be 
assigned a value). 

Refer to table 6-1 for a complete list of the KSAM interface procedures that can be called from 
a BASIC program. 

OPTIONAL PARAMETERS 

When parameters in parameterlist are optional, those parameters are surrounded by brackets. 
In a series of optional parameters, the enclosing brackets are nested. For example: 

CALL name (filenum,status[,paraml [,param2[,param3] ] ] ) 

This notation tells you that parameters can be omitted only from the end of the optional list; 
parameters cannot be omitted from the middle or beginning of the list. For example, if you want 
to specify param3, you must also specify the preceding parameters, paraml and param2; if you 
specify param 2, you can omit the following parameter param3, but not the preceding paraml. 
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Table 6-1. KSAM Procedures for BASIC Interface 



PROCEDURE 
NAME 


PARAMETERS 


FUNCTION 


PAGE 


BKCLOSE 


filenum, 
status 


Terminates processing of KSAM file identified by filenum. 


6-8 


BKDELETE 


filenum, 
status 


Logically removes record from KSAM file; the record to 
be deleted is the record at which the logical record 
pointer is currently positioned. 


6-10 


BKERROR 


status, 
message 


Converts numeric value returned in status parameter to 
character string message. 


6-12 


BKLOCK 


filenum, 

status 

[, condition] 


Dynamically locks KSAM file during shared access, con- 
ditionally depending on condition. 


6-14 


BKOPEN 


filenum, 

status, 

filename 

[, access 

I, dynamic lock 

[, exclusive 

[.sequence] ] ] ] 


Initiates processing of file identified by filenum, named 
by filename. Type of access, whether dynamic locking 
is allowed, whether access is exclusive, and whether 
primary key sequence is checked are options of 
BKOPEN. 


6-16 


BKREAD 


filenum, 

status 

[, parameterlist] 


Reads data from current sequential record of file identi- 
fied by filenum into variables named in parameterlist. 


6-22 


BKREADBYKEY 


filenum, 

status, 

keyvalue, 

keylocation, 

parameterlist 


Reads data from a record identified by keyvalue in the 
key specified by keylocation of the file identified by 
filenum into variables named in parameterlist. 


6-26 


BKREWRITE 


filenum, 

status, 

parameterlist 


Writes data from parameterlist to record at which pointer 
is positioned in file identified by filenum. 


6-29 


BKSTART 


filenum, 

status 

[ , keyvalue 

[, key location 

[, relation] ] ] 


Positions file identified by filenum in preparation for a 
sequential read to the first record with a key in 
keylocation whose value bears the specified relation 
to keyvalue. 


6-32 


BKUNLOCK 


filenum, 
status 


Unlocks file identified by filenum that has been pre- 
viously locked by BKLOCK. 


6-36 


BKVERSION 


status, 
message 


Identifies version of KSAM/3000 currently being used 
returns version number in message. 


6-38 


BKWRITE 


filenum, 

status, 

parameterlist 


Writes data from parameterlist to record in file identi- 
fied by filenum. 


6-39 
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STATUS PARAMETER 



The status parameter is a four-character string variable to which the status of the input-output 
operation is returned. It is the second parameter in every KSAM procedure call except BKERROR, 
in which it is the first parameter. The first character of the status string determines its general 
type. The other three characters supply specific codes to further define the status. The operation 
of a called procedure is successful only if the first character returned in status is zero. Other 
values returned to status indicate the reason an operation was not successful. You can convert 
any status value to a printable message by calling BKERROR. (Refer to table 6-2 for possible 
status values). 

Table 6-2. Values Returned to status Parameter 



FIRST CHARACTER 


REMAINING CHARACTERS 


"0" successful completion 


"0" no further information 
"2" duplicate key value 


"1" at end or beginning of file 


"0" no further information 


"2" invalid key 


"1" sequence error 
"2" duplicate key error 
"3" no record found 
"A" boundary violation 


"1" request denied 


"1" file already locked 


"8" invalid call 


"1" invalid number of parameters 

"2" invalid parameter 

"3" insufficient space for data in parameter! ist 


"9" file system error 


"0" through "255" 

corresponding to file system error codes 
(Refer to complete list in appendix A.) 



Combining the two parts of the status code, the following values may be returned to the status 
parameter: 



if status = "00" 



Successful completion — 

The current input-output operation was completed successfully; no 

duplicate keys read or written. 



'02" 



Successful completion; Duplicate key — 

• In a call to BKREAD or BKREADBYKEY, the current key 
has the same value as the equivalent key in the next sequential 
record; duplicate keys are allowed for the key. 

• In a call to BKWRITE or BKREWRITE, the record just written 
created a duplicate key value for at least one key for which 
duplicates are allowed. 
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STATUS 



= "10" At end condition — 

A sequential read was attempted with BKREAD and there was no next 
logical record in ascending sequence according to the primary key 
value or the current alternate key value. Or an attempt was made by 
BKSTART or BKREADBYKEY to position to a record whose key 
value was less than the lowest key value or higher than the highest 
key value. 

= "21" Invalid key; Sequence error — 

• In a call to BKWRITE for a file opened with sequence checking, 
the record being written contains a primary key that is less than 
a key in a previously written record. 

• In a call to BKREWRITE, the primary key value was changed in 
the program since a successful execution of BKREAD defined the 
record to be rewritten. 

= "22" Invalid key; Duplicate key error — 

An attempt was made to write or rewrite a record with BKWRITE 
or BKREWRITE and the record would create a duplicate key value 
in a key for which duplicates are not allowed. 

= "23" Invalid key; No record found — 

An attempt was made to locate a record by a key value with 
BKSTART or BKREADBYKEY and the record cannot be found. 

= "24" Invalid key; Boundary violation — 

An attempt was made with BKWRITE to write beyond the 
externally defined boundaries of the file; that is, to write past the 
end-of-file. 

= "71" Request denied; File already locked — 

An attempt was made to lock a file with BKLOCK and the file is 
already locked. 

= "81" Invalid call; Invalid number of parameters — 

Too many or too few parameters were specified in the procedure 
call just made. 

= "82" Invalid call; Invalid parameter — 

The specified parameter is not the correct type. For example, a string 
variable was selected where only a numeric variable or expression is 
allowed. 

= "83" Invalid call; Insufficient internal buffer space — 

The data specified in the parameterlist to be read or written will not 
fit into the configured internal buffer space. You may need to have 
certain operating system parameters re-valued. 

= "9xxx" File system error — 

An MPE file system error occurred for which the three-character value, 
xxx is the error code. (Refer to table A-l for a list of these codes.) 
You can call procedure BKERROR to convert the error code returned 
here to a printable message. 
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STATUS 



The value of status can be tested as a whole, or the first character can be tested separately from 
the remaining characters. For example: 



10 DIM S$(4) 



/ 

50 IF S$(l;l) = "0" THEN PRINT "SUCCESS" 
60 ELSE PRINT "ERROR CODE =";S$-< 



-dimension status string S$ 
- test first character only 






f 



100 IF S$(l;l) = "9" THEN DO 

110 PRINT "FILE ERROR = ";S$(2) 

120 DOEND V 






200 IF S$ = "22" THEN DO 

210 PRINT "DUPLICATE KEY ERROR" 

220 DOEND 

300 IF S$(2) = "2" THEN PRINT "DUPLICATE KEY" 



-print entire string 

- test first character 

-print remaining characters 

- test entire string 

- test only remaining characters 



For any status value, you can call the BKERROR procedure and a message is returned that gives 
the meaning of the status code. You can then print this message rather than writing your own. 
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KSAM LOGICAL RECORD POINTER 

Many of the KSAM procedures use a logical record pointer to indicate the current record in the file. 
This pointer points to a key value in the key file that identifies the current record in the data file. 
The particular key used, if the file has more than one key, is the key last specified in the current or 
a previous procedure call; by default it is the primary key. 

Procedures that use pointers are either pointer-dependent or pointer-independent. Pointer-dependent 
procedures expect the pointer to be positioned at a particular record in order to execute properly. 
Pointer-independent procedures, on the other hand, execute regardless of where the pointer is posi- 
tioned and, in most cases, they position the pointer. (Refer to table 6-3 for a summary of those pro- 
cedures that either position the pointer or are dependent on that position.) 



Table 6-3. Positioning the Logical Record Pointer 



Procedure 
Name 


Pointer- 
Dependent 


Position of Pointer After 
Execution of Procedure 


BKSTART 


NO 


Points to key whose value was specified in call. 


BKREADBYKEY 


NO 


Points to key whose value was specified in call. 


BKWRITE 


NO 


Points to key whose value is next in ascending key 
sequence to key value in record just written. 


BKREAD 


YES 


Pointer remains positioned to key value for record just 
read; unless next call is to BKREAD, or to BKREWRITE 
followed by BKREAD, in which case, the pointer is 
moved to the next record in key sequence before the 
read. 


BKDELETE 


YES 


Points to next key value in ascending sequence follow- 
ing key value in record just deleted. 


BKREWRITE 


YES 


Pointer remains positioned to key value for record just 
modified; unless any key value in record was changed, 
in which case, it points to next key in ascending se- 
quence after the key in the modified record. 




Note: BASIC procedures do not access a KSAM file in chronological sequence or by record number; they ignore 
the chronological pointer. 



SHARED ACCESS 

Particular care must be taken when using the logical record pointer during shared access. Since the 
record pointer is maintained in a separate control block for each open file, one user may cause the 
record pointer to be inaccurate without other users being aware of it. To avoid this problem, you 
should always lock the file in a shared environment before calling any procedure that sets the 
pointer and leave the file locked until all procedures that depend on that pointer have been exe- 
cuted. Thus, if you want to read the file sequentially, delete a record, or modify a record, you 
should lock the file, call a procedure that sets the pointer (such as BKSTART), and then call 
BKREAD, BKDELETE, or BKREWRITE. When the operation is complete, you can then unlock 
the file to give other users access to it. 
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BKCLOSE 

A call to BKCLOSE terminates file processing for the specified file. 

CALL BKCLOSE ifilenum,$tatus) 

When processing is completed, a KSAM file should be closed with a call to BKCLOSE. No further 
processing is allowed on the file until a BKOPEN procedure call re-opens the file. 

BKCLOSE can be executed only for a file that is open. 

PARAMETERS 

filenum A numeric variable containing the file number that identifies the file; 

this number was returned by the last call to BKOPEN. It should not 
be altered until the file is closed with a successfull call to BKCLOSE. 
(Required parameter) 

status A four-character string variable to which is returned a code that 

indicates whether or not the file was successfully closed and if not, 
why not. The first character is set to "0" if the close is successful, 
to another value if not. (Refer to the Status Parameter discussion 
earlier in this section.) 
(Required parameter) 

USING BKCLOSE 

After calling BKCLOSE, you should check the status parameter to determine if the file was 
closed successfully. A successfully closed file is no longer available for processing until it is 
re-opened. Note that a KSAM file can be closed and then re-opened in order to specify a different 
access mode or type of processing. 

The BKCLOSE procedure does not remove the file from the system. To do this, you should use 
the PURGE command of the KSAMUTIL program. 

The example in figure 6-1, closes a file identified by the filenumber in F. It then checks the 
status and prints a message if the status shows any code except the zero for successful completion. 
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BKCLOSE 



JfclO REM »«e»»»«»***»» ,t ** ,, **»»**«»»***»*»*»»»********* l, **** s »**« 
3620 REM » CLOSE A KSAM FILE » 

3630 REM »#«»*»*«**oo»»*»»»*tt«««»»#*»«#««*»»««»*»******«**»*»«'»» 

36*0 REM 

3 6S n rem F IS THE FILE NUMBER OF ft KSAM FILE 

3660 REM DEFINED BY A CALL TO BKOPFN 

3670 REM 

36BO CALL PKCLOSE<F,S$) 

36S0 REM 

3700 REM NOW DETERMINE WHETHER THIS CALL SUCCEEDED 

3710 REM 

3720 IF SS[im<>"0» THtN DO 

3730 REM N$ CONTAINS THE NAmE OF THE KSAM FILE 

3740 REM SS CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 

3750 PRINT "UNABLE TO CLOSE "|N«|» ERROR "iSSUJlH" DETAIL "|SSt23 

3760 CALL BKERROR(S$»M<) 

3770 PRINT M$ 

3760 OOENO 



Figure 6-1. Closing a KSAM File with BKCLOSE 



6-9 



BKDELETE 

Logically deletes a record from a KSAM file. 
CALL BKDELETE (filenum, status) 



A call to BKDELETE logically deletes the last record read from or written to a KSAM file. A 
logically deleted record is marked by two delete characters (ASCII code 255) in the first two 
character positions in the record. The deletion characters indicate that the record is inaccessible, 
although it is not physically removed from the file. The connection between a data record marked 
for deletion and the key file is severed. 

When a file with deleted records is copied by FCOPY to a new KSAM file, records marked for 
deletion by BKDELETE are not copied. This use of FCOPY provides a means to compact a file 
in which many records have been marked for deletion but physically use space in the file. 

To use BKDELETE, the file must be open in the access mode that allows update. If access is shared, 
the file must also be opened with dynamic locking allowed (lock = 1), and the file must be locked 
by BKLOCK before records are deleted. 



PARAMETERS 

filenum A numeric variable containing the file number that identifies the 

file; this number was returned by the last call to BKOPEN. It should 
not be altered unless the file is closed with a successful call to 
BKCLOSE. 
(Required parameter) 

status A four-character string variable to which is returned a code that 

indicates whether or not the call to BKREWRITE was successful and 
if not, why not. The first character is set to zero if the call succeeds, 
to another value if not. (Refer to Status Parameter discussion earlier 
in this section.) 

USING BKDELETE 

Before calling BKDELETE, you can read the record to be deleted from the KSAM file into the 
BASIC program. (The record to be deleted can also be specified as the last record written or 
rewritten.) Using either BKREAD or BKREADBYKEY, read record into variables named in the 
read call. When BKDELETE is successfully executed, the first two characters of the record just 
read are marked for deletion. Then the record is written back to the file. Any connections between 
the record and key entries in the key file are severed. The associated key entries are physically 
deleted from the key file although the data record remains in the data file. Data space is not re- 
used in order to maintain the chronological order of the file. Because BKDELETE requires that 
the record be both read and written, you must open the file for update (access = 4) before calling 
this procedure. 

After calling BKDELETE, you should check the status parameter to make sure that the delete was 
successful. 
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BKDELETE 



In the event that you deleted a record in error, you can recover the information in the data record 
by copying the data file with the NOKSAM option of FCOPY. You can copy the data file to 
another non-KSAM file or to the list device. With this FCOPY option, the deleted records as well 
as active records are copied. In order to make use of this recovery procedure, you may want to 
leave the first two characters of any KSAM record empty of data. In particular, you should not 
specify keys in those two characters. 

FCOPY can also be used to permanently remove any records that were logically deleted with 
BKDELETE. When you use FCOPY to copy your KSAM file to a newly created KSAM file, only 
active records are copied. Records marked for deletion are dropped from the data file during the 
copy. The new file is more compact, particularly if many records had been deleted from the old 
file. (Refer to FCOPY description in section II for more information.) 

SHARED ACCESS. When access is shared, the call that positions the pointer to the record to be 
deleted should be included in the same pair of BKLOCK/BKUNLOCK calls as the call to 
BKDELETE. This insures that no other user alters the record position between the call that locates 
the record and the call that deletes it. (Refer to table 6-3 for a list of the procedures that position 
the pointer and those that depend on the pointer.) 

Figure 6-2 contains an example illustrating the logical deletion of a record from a KSAM file. 



3c*0 REM •»•••«••••»•••••••••••••••••»•••••••••••••••••••••»••» 

3JSo REM • REMOVE A RECORD FROM A KSAM FILE » 

3c60 REM »»••••••••»••••••••••••«••••••••••••••••••••••••••*••» 

3370 REM 

3J80 REM F IS THE FILE NUMBER OF A KSAM FILE OPENED BY A CALL TO BKOPEN 

3290 REM NOTE THAT F0« BKDELETE, PKOPEN ACCESS MODE MUST c * FOR UPDATE 

3295 REM 

3300 HEM THE RECORD TO HE OtLETEO MUST FIRST BE REAU... 

3305 REM AN ASSUMPTION has BEEN MADE THAT THE RfCORO TO BE READ 

3310 REM ANO DELETED CONTAINS THE SAME INFORMATION That WAS 

3320 REM WRITTEN IN THE BKWRITE FXAMPLE. 

3330 REM 

33«0 CALL BKREAD(F 1 sSiBl$,B2*,ASr»].A3t*J,A2[»)| 

3330 REM 

3360 REM NOW DETERMINE WHETHER THF CALL WAS SUCCESSFUL 

3370 REM 

3380 IF SSCltl]<>"0" THtN 00 

3390 REM NS CONTAINS THE NAmE OF THE KSAM FILE 

3*00 RE M S* CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 

3*10 PRINT "UNABLE TO READ »|NI|« ERROR "|SS(l|lji" DETAIL "IS*C2J 

3*20 CALL BKERROR |S$|M») 

3*30 PRINT MS 

3*35 GOTO 3620 

3**0 DOEND 

3*50 REM 

3*60 CALL BKOELETE(F,S»> 

3*70 REM 

3*80 REM NO" DETERMINE WHETHER THIS CALL SUCCEEDED 

3*90 REM 

3S00 IF SS[1U1<>"0» THLN 00 

3510 RE" NS CONTAINS THE NAME OF THE KSAM FILE 

3520 REM S* CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 

3530 PRINT "UNABLE TO DELETE RECORD FROM "|NS| 

3535 PRINT " ERROR " l*>s[ 1 1 1 J I" DETAIL "ISStSl 

35*0 CALL BKERROR(SS,MS| 

3550 PRINT MS 

3560 GOTO 3620 

3ST0 DOEND 

3575 PRINT "DELETED RECORD CONTAINS "IB1SIB2SI 

3ST6 MAT PRINT AS 

3577 MAT PRINT A3.A? 

35B0 REM 

3590 REM THE PROGRAM CONTINUES 



Figure 6-2. Deleting a Record With BKDELETE 
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A call to BKERROR returns a message corresponding to the status value. 



CALL BKERROR (status,message) 



Call this procedure in order to get a printable string of characters that describes the condition that 
corresponds to the value of the status parameter. The string of ASCII characters returned in 
message can be printed as an error message. 



PARAMETERS 



status 



message 



is a four-character string variable to which is returned a numeric 
value in printable form following execution of any of the procedures 
described in this section. The value in status is used to derive the text 
in message. 
(Required parameter) 

is a string variable which will contain the text describing the error 

whose code has been returned to status. This parameter should be 

dimensioned to at least 72 characters in length. If the message length 

exceeds the dimensioned length of message, a truncated text is 

provided. 

(Required parameter) 



USING BKERROR 



The following example illustrates the use of BKERROR. Two strings are dimensioned for 
message; one (M$) is sufficiently long, the other (N$) causes truncation of the message. Assume 
that the status code in S$ is the value "22". 

10 DIM S$(4),M$(72),N$(24) 

20 REM . . S$ IS THE STATUS STRING 

30 REM . . M$ IS A SUFFICIENTLY LARGE STRING 

40 REM . . N$ IS TOO SMALL FOR THE MESSAGE 

50 REM . . ASSUME S$ CONTAINS THE VALUE "22" 

60 REM . . 



100 CALL BKERROR (S$,MS) 

110 PRINT "ERROR ";S$(1;1) ; " DETAIL ";S$(2);" ";M$ 

120 CALL BKERROR (S$,M$) 

130 PRINT "ERROR "S$(1;1);"DET AIL ";S$(2);"";N$ 
RUN 



_r 



-full message 



ERROR 2 DETAIL 2 INVALID KEY VALUE. DUPLICATED KEY VALUtf 

truncated message 



ERROR 2 DETAIL 2 INVALID KEY VALUE. DUPL , 

N 
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In another example, BKERROR is called to retrieve the message corresponding to the MPE file 
system error code returned when the first character of status is "9". 

10 DIM S$(4),M$(72) 

• 

50 IF S$(l;l) = "9" THEN DO 
60 CALL BKERROR(S$,M$) 

70 PRINT "FILE ERROR ";S$(2); U MEANS ";M$ 
80 DOEND 

Suppose the value returned in status is "9172", then the routine above prints the following 
message when the program is run : 

FILE ERROR 172 MEANS KEY NOT FOUND; NO SUCH KEY VALUE 

A list of the MPE file system error codes and their meaning is contained in table A-l of appendix A. 
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Dynamically locks KSAM file during shared access. 



CALL BKLOCK(filenum,status[, condition ] ) 



When more than one user accesses the same file, BKLOCK can be used to make access to the file 
exclusive for one user while he writes to or updates the file. In order to use BKLOCK, the file 
must be opened with dynamic locking allowed by all users who are sharing the file. When finished 
with the changes that required exclusive access, the user who has locked the file with BKLOCK 
should unlock it with BKUNLOCK. 

Note that a file opened for shared access must be locked by BKLOCK before the file can be modi- 
fied by BKWRITE, BKREWRITE, or BKDELETE. 



PARAMETERS 

filenum 



status 



condition 



A numeric variable containing the file number that identifies the file; 
this number was returned to filenum by the last call to BKOPEN. It 
should not be altered unless the file is successfully closed by BKCLOSE. 
(Required parameter) 

A four-character string variable to which is returned a code that indi- 
cates whether or not the call to BKLOCK was successful and if not, 
why not. The first character is set to zero when the call succeeds, to 
another value if it fails. (Refer to the Status Parameter discussion earlier 
in this section.) 
(Required parameter) 

A numeric expression whose value determines the action taken if the 
file is locked by another user when BKLOCK is executed. If the value 
of condition is: 

zero-locking is unconditional; if the file cannot be locked immediately 
because another user has locked it, your program suspends execution 
until the file can be locked, (default value) 

non-zero-locking is conditional; if the file is already locked, control 

returns immediately to your program with status set to "71". 
(Optional parameter) 
Default: If omitted, locking is unconditional. 



USING BKLOCK 

In order to call BKLOCK, the file must be opened with dynamic locking allowed. That is, the 
parameter lock in the BKOPEN procedure must be set to 1. Also, since dynamic locking is useful 
only when access is shared, probably the file will have been opened with the exclusive parameter 
in BKOPEN set to 3. 
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NOTE 

All users who share access to the file must agree to allow dynamic 
locking in order for any user to dynamically lock the file with 
BKLOCK. 



The note above points out that users who share the same file should cooperate on how they will 
share the file. Unless they all agree to allow locking, no one will be able to lock the file. Also, it is 
important to avoid situations where one user locks the file and forgets to unlock it. If this occurs 
when condition is set to a non-zero value, the calling process is not halted. But if the file is locked 
already and if you attempt to lock a file with condition omitted or set to zero your process is 
halted until the other user either unlocks the file or logs off. 

You should always check the status parameter immediately following a call to BKLOCK in order 
to determine if the call was completed successfully. If you locked with condition set to a non- 
zero value, you should check if the file was locked before continuing. If it was locked, status will 
have a "0" in the first character, but if another user had locked the file preventing your call to 
BKLOCK from working, then status contains the value "71". 

Figure 6-3 contains an example of locking a file with BKLOCK. 



830 


REM •»•»#•♦•••••#•*••**••*•••**••#*•••#•#••••**•*••*•••###•* 


840 


REM » LOCK A KS*M FILE • 


850 


REM «••»•»*•••»»*••»»•*«••»*«•*•*•»«•••♦••*•»**•**»*•*»»«•«* 


855 


REM 


860 


REM F IS THE FILE NUMBER OF A KSAM FILE 


870 


REM OPENED BY A CALL TO BK0PEN 


890 


REM 


900 


REM THE THIRD PARAMETER INDICATES THAT LOCKING IS 


910 


REM TO TAKE PLACE UNCONDITIONALLY 


930 


REM 


930 


CALL BKLOCK(F,S*»0) 


940 


REM 


950 


REM NOW DETERMINE WHETHER THIS CAUL HAS SUCCEEDED 


960 


REM 


970 


IF S$tHlJ<>"0» THtN 00 


980 


REM NS CONTAINS THE NAME OF THE KSAM FILE 


990 


REM SS CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 


1000 


PRINT "UNABLE TOL0CK "|NS|" ERROR "ISSUI1JI" DETAIL "ISSC2] 


1010 


CALL BKERROR(SSrMS) 


1020 


PRINT MS 


1030 


DOEND 



Figure 6-3. Dynamically Locking a KSAM File with BKLOCK 
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A call to procedure BKOPEN initiates file processing. 



CALL BKOPEN (filenum,status,name [ y acces$[,lock[,exclusive[,sequence\ ] ] ] ) 



In order to process a KSAM file, it must be opened with a call to the BKOPEN procedure. 
BKOPEN initiates processing, and optionally specifies how the file is to be processed. BKOPEN 
does not create the file; it must have been created previously. You can create a KSAM file 
through the BUILD command of the KSAMUTIL program (refer to section II). 

To open a file means to make it available for processing. You can also specify how the file is to be 
accessed (whether for input, output, input and output, or for update), whether dynamic locking 
is allowed, whether access to the file can be shared, and whether records written to the file are to 
be checked for primary key sequence. Default values are assigned for the optional parameters. 
If you want to change the current processing or access method, you must close the file and then 
open it again with the parameters set to new values. 

PARAMETERS 



filenum 



status 



name 



access 



A numeric variable whose value identifies the file opened by the call 
to BKOPEN. Since the value of filenum identifies the file in other 
CALL statements, it must not be changed while the file is open. 
(Required parameter) 

A four-character string variable to which is returned a code to indicate 

whether or not the file was successfully opened and if not, why not. 

The first character is set to "0" if the open is successful, to another 

value if not. (Refer to Status Parameter discussion earlier in this 

section.) 

(Required parameter) 

A string expression containing the name of the KSAM file to be 
processed. This name is the actual designator assigned to the file when 
it was created, or else it is a back reference to a formal designator 
specified in a :FILE command, in which case, name has the form 
*formal designator. 
(Required parameter) 

A numeric expression whose value indicates one of the permissible 
access types : 



Read only. 

1 Write only. 

2 Write only. 



Use of procedures BKWRITE, BKREWRITE, 
and BKDELETE are prohibited. 

Deletes previously written data. Use of the 
procedures BKREAD, BKREADBYKEY, 
BKREWRITE, BKDELETE, and BKSTART 
are prohibited. 

Saves previously written data. Use of the 
procedures prohibited by the access=\ , above, 
are also prohibited by access=2. 
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lock 



exclusive 



3 Read and write. Use of procedures BKREWRITE and 

BKDELETE prohibited. (Default value.) 

4 Update access. Allows all procedures described in this section. 
(Optional parameter) 

Default: If omitted,or out of range, access is 3, read and write access. 

A numeric expression whose value indicates whether dynamic locking 
can take place. Acceptable values are: 

Disallow dynamic locking and unlocking. 

Use of procedures BKLOCK and BKUNLOCK 
prohibited. (Default value.) 

1 Allow dynamic locking and unlocking. 

Procedures BKLOCK and BKUNLOCK may 
be used to permit or restrict concurrent access 
to the file. 

(Optional parameter) 

Default: If omitted, or out of range, lock = to disallow dynamic 
locking 

A numeric expression whose value indicates the kind of exclusive 
access desired for this file. If this parameter is omitted or is not one 
of the following acceptable values, the default is assumed: 

Depends on access parameter. 

If access = (read only), then users share 
access to this file as if exclusive were set to 3. 
If access is not = 0, then access to this file is 
exclusive as if exclusive were set to 1. 



Exclusive. 



Semi-exclusive. 



Prohibits other access to this file until either 
the file has been closed or the process 
terminated. Only the user who opened the 
file can access it while it is currently open. 

Other users can access this file, but only for 
read access. The file cannot be accessed to 
write, rewrite, or delete records until it is 
closed or the process is terminated. (Default 
value.) 



3 Shared. Once the file is opened, it can be accessed 

concurrently by any user in any access mode, 
subject only to the MPE security provisions 
in effect. 

(Optional parameter) 

Default: If omitted, or out of range, exclusive = 2, semi-exclusive 
access. 
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sequence A numeric expression whose value indicates whether records written 

to the file will be checked for primary key sequence or not. 
Acceptable values are : 

No sequence When records are written to the file, primary 
checking. key values can be in any order; their sequence 

is not checked. (Default value. ) 

1 Sequence As each record is written to the file, KSAM 
checking. checks to insure that its primary key value is 

greater than the primary key value of any 
previously written records; if duplicates are 
allowed for this key, then the primary key can 
be equal to that of the previously written 
record. 

(Optional parameter) 

Default: If omitted, or out of range, sequence = 0, no sequence 
checking 



USING BKOPEN 

After calling BKOPEN, you should always check the status parameter to determine whether the 
open was successful. Upon successful execution of BKOPEN, the file named in name is available 
for processing; an identification number is assigned to this file and returned to filenum where it 
is available to identify the open file in other calls. Until the file is successfully opened with 
BKOPEN, no operation can be executed that references the file either explicitly or implicitly. 

If only the first three parameters are specified, and the file is opened successfully, the file has the 
following default characteristics: 

• Read and Write access; you can read from and write to but not update the file. 

• Semi-exclusive access; other users can read from but not write to or update the file. 

• Dynamic locking not allowed; you cannot lock or unlock a file. 

• No sequence checking; records can be written in any order without checking sequence of 
primary key values. 

ACCESS MODES. There are two types of write only access : one clears any existing records 
before writing the specified records to the file (access = 1); the other saves existing records and 
writes the new records after those already written (access = 2). Both these access modes do not 
permit any read or update access to the file. 

Read-only access (access = 0) can be specified if you want to insure that the file is not changed. 
This mode prohibits the writing of new records, and rewriting or deleting of existing records. In 
read-only mode, you can position the file, and read records in either sequential or random order. 

The default access mode (access = 3) allows you both to read records from and write records to a 
file, but not to change or delete existing records. If you plan to read and write records during 
the same process, but do not want to alter existing records, use this access mode. 



6-18 



BKOPEN 



If you want to rewrite or delete existing records in a KSAM file, you must open with access = 4. 
This mode allows you to use the BKREWRITE and BKDELETE procedures, as well as all the 
other procedures described in this section. 

Table 6-4 summarizes the procedures you may call depending on the access parameter value you 
specify in BKOPEN. 



Table 6-4. Procedures Allowed by BKOPEN access Parameter 



BKOPEN access Parameter 


Procedures 
Allowed 


Read-only 
iaccess=0) 


Write-only 
with Clear 
(access=1) 


Write-only 
with Save 
{access=2) 


Read/Write 

{access=3) 


Update 

(access=4) 


BKREAD 

BKREADBYKEY 

BKSTART 


BKWRITE 


BKWRITE 


BKREAD 
BKREADBYKEY 
BKSTART 
BKWRITE 


BKREAD 

BKREADBYKEY 

BKSTART 

BKWRITE 

BKREWRITE 

BKDELETE 


BKCLOSE 
BKERROR 


BKCLOSE 
BKERROR 


BKCLOSE 
BKERROR 


BKCLOSE 
BKERROR 


BKCLOSE 
BKERROR 



SHARED ACCESS. By default in a multi-user envornment, all users whose MPE security 
restrictions allow them to access your file can read the file, but they cannot change the file or add 
new records to it. This is the default specification of the exclusive parameter in BKOPEN 
(exclusive=2). It is independent of the value of the access parameter. 

If you want to prevent other users from reading the file as well as writing to it, you must specify 
this by setting exclusive=l. This setting allows only you to read from, write to, or alter the 
file. 

Another alternative is to set exclusive=0, thereby allowing other users access to the file only when 
it is opened for read only {access=Q). This setting of the exclusive parameter prevents any access 
by other users when the file is opened for any form of write or update (accessf 0) . This means that 
you and other users share read access to the file, but only you can write to or change the file. 

You can choose to completely share access to the file, reading and/or writing and updating, by 
setting the exclusive parameter to 3. 

(Refer to table 6-5 for a summary of the relation between the exclusive parameter and the 
access parameter.) 
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Table 6-5. Relation of exclusive Parameter to access Parameter 





exclusive = 


exclusive = 1 


exclusive = 2 
(default) 


exclusive = 3 


access = 
(read only) 


shared 


exclusive 


semi-exclusive 


shared 


access 4 
(write only, 
read/write, 
or update) 


exclusive 


exclusive 


semi-exclusive 


shared 



DYNAMIC LOCKING. When access is shared, it is good practice to allow dynamic locking so 
that individual users can dynamically lock the file while performing any updates to the file. 
The file can be unlocked as soon as the update is complete. An update to a file is when you 
write a new record, delete a record, or rewrite an existing record. When access is exclusive or 
semi-exclusive, there is no need for dynamic locking since only the user who has opened the 
file can update the file. 

Dynamic locking should also be allowed if access is shared and you plan to read the file sequentially. 
This is because the sequential read procedure (BKREAD) is dependent on the position of the logical 
record pointer and, in a shared environment, this pointer can be changed by other users unless the 
file is locked (Refer to table 6-3 for a list of the pointer-dependent procedures.) 

SEQUENCE CHECKING. When sequence checking is specified, you must write records to the 
file in primary key sequence. An attempt to write a record out of sequence causes the write to 
fail and the value "21" is returned to status following a call to BKWRITE. (Refer to the description 
of Status earlier in this section.) As a result of sequence checking, the chronological and the 
primary key sequence of records in your file is the same. Since the BASIC KSAM procedures have 
no provision to read the file in chronological sequence, you may want to specify sequence checking 
for any file that you will want to read in that order. With sequence checking, a file read in logical 
order by primary key (the default for BKREAD) is also read in chronological order. 

The example in figure 6-4 shows how to use BKOPEN to open a KSAM file for input and output 
(default access), with dynamic locking (/ocfe=l), for shared access (exclusive=3), and without 
sequence checking (default sequence). 
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DIM 


■-■■"- * 


■■■I- " - .. l .- 


ao 


PIH 


Nkt26 ,«^_ filename \ variable dimensions 


JO 


DIM 


iiillilliiil^^ 


M t » ' e- .3 ^* ~ f/*£-«"t*/;* x 


«n 


INTEGER AC103 


50 


DIM 


B*C12) 


55 


INTEGE« J 


60 


DIM 


81* t 1 J 


65 


DIM 


9?*C2] 


70 


INTEGER A2C2),fl3C3J ,A515] 


(30 


REM 




90 


REM 


THE KSAM/3000 FILE WAS BUILT WlTHj 


loo 


REM 


REC-80, 16, F, ASCII 


no 


REM 


KEVsB»2,2, ,UUP 


120 


REM 


SOiRECORD LENGTH IS 2 BYTFS, FIXED, TYPE ASCII, 16 REC/BLOCK, 


130 


REM 


THE KEY IS 2 CHARACTERS LONG , STARTING IN CHARACTER 3 OP RECORD 


135 


REM 




140 


REM 


»««««»«•«»«»«»««««»«««««»«•»«»«<>»««»«««»»««#«««»«««.»««»» 


145 


REM 


* OPEN A KSAM FILE « 


150 


REM 


««»»»««««««»«»»«««««»««ft«««««tt«««e«»«»«i»««*»e»«»» »»«»««« 


160 


REM 




170 


REM 


THE FILE NAME IS IN n$ 


175 


REM 


THE STATUS OF THE CALL IS RETURNED IN S$ 


180 


REM 


WHEN SUCCESSFUL, BKOPEN RETURNS A FILE DUMBER IN F 


190 


REM 


INPUT-OUTPUT ACCESS IS SPECIFIED IN J 


200 


REM 


DYNAMIC LOCKING IS AlLOWFO IN D 


210 


REM 


SEMI-EXCLUSIVE ACCESS IS INDICATED IN E 


??Q 


REM 

*. s -. ■ 




2%0 


K » J !_ , - EC j ■'• .J--.- -•■'* ;, ■..",'. 


aso 


J»3- 


- access read/write 


260 


' s-. 


fiynnmip. locking allowed 


270 
280 


CALL 




. BIROPEN :f t? it Ni , J , i E ) 


?<3 


REM 




300 


>• -: u 


.-.- JETERMINfc "HETHtfi - - v CALL SUCCEEDED: 


310 


., ; • 




320 


IF SI[MJ3<>"0" T Mfc N .; C 


330 


-'-•' s>* \.^ '"-■ status :z:~. ■-;■" '■•• the :■-..■.. to j <"»?.-. 


340 


J»F* n* I&.?He NA«*€ .0? THE FH.& ' , ' ' 


350 


Pf 


JINT "UNABLE TO OPEN »,N«|" ERROR «• 1 SSC i U > 1 "DETAIL "»S*C21 
L aKERROR SS,"i! 


360 


c* 


330 


•pwinT fn ' • ' • ■ ' ' > ' '■ ' ' . - ' •■ 


ooto Joiu ■« to close tne file 


390 


D0END 


400 


REM 




4X0 


REM 


THE PROGRAM CONTINUES 



Figure 6-4. Opening KSAM File with BKOPEN 
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Transfers the next logical record from a KSAM file to a BASIC program. 
!}■$£■ •.; / ; CAtL BKREAD(fitemm,stptu$lrparainete?lt8t] ) 



A call to BKREAD transfers the contents of a record from a KSAM file to a storage area defined 
by a list of variables in a BASIC program. The record read is that at which the logical record pointer 
is currently positioned. In a series of calls to BKREAD, records are read in ascending order by 
key value. The primary key is used unless a previous call to BKSTART or BKREADBYKEY has 
positioned the pointer to an alternate key. The file must have been opened with an access mode 
that allows reading. 



PARAMETERS 

filenum 



status 



parameter list 



A numeric variable containing the file number that identifies the file; 
this number was returned by the last call to BKOPEN. It should not 
be altered unless the file is closed by a successful call to BKCLOSE. 
(Required parameter) 

A four-character string variable to which is returned a code that indicates 

whether or not the call to BKREAD was successful and if not, why 

not. The first character is set to zero when the call succeeds, to another 

value if not. (Refer to the Status Parameter discussion earlier in this 

section.) 

(Required parameter) 

A list of variables separated by commas into which the data in the 
record is read. The contents of the record are read into the variable 
(or variables) until the physical length (or combined physical lengths) 
of parameterlist is exhausted, or the end of the record is reached. 
(Optional parameter) 

Default: If omitted, the logical record pointer is positioned to the 
beginning of the next record in key sequence. 



USING BKREAD 



After calling BKREAD, you should always check the status parameter to determine whether the 
read was successful. Upon successful completion of BKREAD, the variables specified in 
parameterlist contain data read from the record at which the record pointer was positioned when 
BKREAD was called. Note that if parameterlist is omitted, the record pointer is positioned to the 
beginning of the next logical record, effectively skipping the current record. 

In order to use BKREAD, the file must be opened for input. The BKOPEN access parameter 
should be zero if you only plan to read or position a record. To both read from and write to the 
same open file, you either omit the access parameter or set it = 3. If you want to rewrite or update 
as well as read records, you must set access = 4. 
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Values are read from the current record into the variables specified in parameterlist according to 
the type and length of the variable. For example, consider the following code: 

10 DIM G$(3),H$(3),S$(4) 

20 INTEGER L,F 

30 CALL BKREAD (F,S$,G$,H$,L) 

parameterlist 




If the record being read contains only the word SCRABBLE, this word is read into the specified 
variables as if they were assigned by the statements: 

100 G$="SCR" 
110 H$="ABB" 
120 L=NUM("LE") -. assigns numeric equivalent of string "LE" to L 



NOTE 

Each variable in the parameterlist is filled to its current physical 
length before proceeding to the next variable. 

The following calls omit the parameterlist in order to skip forward two records: 

210 CALL BKREAD(F,S$) . , . . 

220 CALL BKREAD(F;S$) Z_== skl P two records 

The records skipped are not the next records physically placed on the file, but are the next two 
in logical sequence according to the value of the current key. The particular key used for the read 
sequence can be selected with a call to BKSTART or BKREADBYKEY. BKSTART can also be 
used to position the file to the beginning of the record with the lowest key value in the selected 
key (Refer to BKSTART following BKREAD discussion.) 

The example in figure 6-5 assumes that the record pointer has been positioned to the beginning of 
the first record in primary key sequence. Assume that the file being read was opened in the example 
in figure 6-4, the records read were written in the example in figure 6-11. 

Each record contains five integers followed by five undefined words (garbage) followed by a string 
of three characters. The record is read into 

A5 a 5-word integer array 

A2 a 2-word integer array 

A3 a 3-word integer array 

Bl$ a 1 -character string 

B2$ a 2-character string 

The five integers that were written to the beginning of each record are read into array A5. The 
next two arrays A2 and A3 receive the undefined values that filled the next five words of the 
record. The first string character is read into Bl$, the next two into B2$. 
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SHARED ACCESS. If you open the file for read-only access (access=0), and the exclusive param- 
eter is allowed to default to zero, then more than one user can share read access to the file. In this 
case, or if you specifically indicate shared access, you should also allow dynamic locking in order to 
read records from the file in key sequence. This is necessary because BKREAD depends on the cur- 
rent position of the logical record pointer. (Refer to table 6-3 for a list of the pointer-dependent 
procedures.) 

For example, if you plan to read the file sequentially starting from a particular key value, use the 
following sequence of calls: 

BKOPEN- open file for read-only, shared access, allow dynamic locking 

BKLOCK- lock file 

BKSTART-" position pointer 

BKREAD loop-« read file in sequence from original pointer position 

BKUNLOCK -* unlock file when last record read 
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10 


DIM S*t4J 


20 


DIM N«126} 


30 


DIM MtC 72] 


to 


INTEGER ACK'J 


SO 


DIM HTC123 


95 


INTEGER J 


60 


DIM 81 *U ] 


b<3 


DIM ri?*l2) 


70 

* 


INTFGE* A2t 21 , A3C33 i A5C5] 


• 

1310 


REM »»«»«»«»*»««•*«»*««•«»•»«««««•*»*•««•»«•«»•*«««»«•*•»• 


1320 


REM » READ FROM A KSAM FILE « 


1330 


REM •»••*••**»•••*•••••••••*•##•••••*•••••••••**•• •»»«»«»# 


1340 


REM 


1350 


REM F IS THE FILE NUMBER OF A KSAM FILE 


1360 


REM OPENED BY A CALL TO BKOpEN 


1370 


REM 


1380 


REM AN ASSUMPTION MAS BEEN MADE THAT THE RECORD TO BE READ 


139 


REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN TO 


1*00 


REM THE FILE BY TH6. EXAMPLE TO WRITE A KSAM FILE 


1410 


REM 


1*20 


CALL BKREAD(F,s$»81$,B2$,A5t»l,A3C»3»A2C*J) 


1430 


REM 


1440 


REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED 


1450 


REM 


1460 


IF S*C1»13<>"0" THEN DO 


1470 


REM N$ CONTAINS THE NAME OF THE KSAM FILE 


1480 


REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 


1490 


PRINT "UNABLE TO REAO »|N*»» ERROR "jSSClllli" DETAIL »ISS(21 


1500 


CALL BKERROR(SSiMS) 


1510 


PRINT MS 


1520 


REM 


1530 


REM TEST FOR END OF FILE 


1540 


REM AND POSITION TO LEaST VALUED PRIMARY KEY 


1550 


IF S*C1|1J«»1" THEN 1080 


1560 


GOTO 3620 


1570 


OOENO 


1580 


REM 


1590 


REM ECHO WHAT WAS HEAD 


1600 


REM 


1610 


PRINT ''RECORD CONTAINS "|B1«|B2S 


1620 


MAT PRINT A5 


1622 


MAT PRINT A3iA2 


1630 


REM 


1650 


REM THE CONTENTS OF B1S*»1», OF B2*«»23« 


1660 


REM THE CONTENTS OF AS (1 ) THROUGH A5<5> ARE 1 THROUGH 5. 


1670 


REM THE CONTENTS OF A3 AND Ag ARE UNKNOWN. 


1680 


REM 


1690 


REM THE PROGRAM CONTINUES 



Figure 6-5. Reading From a KSAM File with BKREAD 
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Transfers record identified by particular key value from KSAM file to BASIC program. 

CALL BKREADBYK&Y6^/iM/n,tffliK$,^^ 

A call to BKREADBYKEY locates and reads a record into a storage area identified by a list of 
variables in the BASIC program. The record to be read is located by matching the specified keyvalue 
with an identical value stored in the record starting at keylocation. The record value and the value 
specified in keyvalue must match exactly, or an error code is returned to status. To use 
BKREADBYKEY, the file must be open in an access mode that allows reading. 

You cannot use BKREADBYKEY to locate a record by generic or approximate key values. For 
this purpose you can call BKSTART followed by a call to BKREAD. (Refer to the discussion of 
BKSTART.) 



PARAMETERS 

filenum 



status 



keyvalue 



keylocation 



parameterlist 



A numeric variable containing the file number that identifies the file; 
this number was returned by the last call to BKOPEN. It should not 
be altered unless the file is closed with a successful call to BKCLOSE. 
(Required parameter) 

A four-character string variable to which is returned a code that indi- 
cates whether or not the call to BKREADBYKEY was successful and 
if not, why not. The first character is set to zero if the call succeeds, 
to another value if not. (Refer to the Status Parameter discussion 
earlier in this section.) 
(Required parameter) 

A string or numeric expression whose value is compared to a key value 
in the record. The record pointer is positioned to the first record with 
a key value at keylocation that is exactly equal to the specified keyvalue. 
In order to match exactly, the record value and keyvalue must have the 
same logical length. 
(Required parameter) 

A numeric expression whose value indicates the starting character posi- 
tion in each record of the key used to locate the record to be read by 
BKREADBYKEY. The characters in a record are counted starting with 
1. If the value of keylocation is zero, the primary key is assumed. The 
primary key also may be specifically indicated by its location in the 
record. 
(Required parameter) 

A list of variables separated by commas into which the data in the 
record is read. The contents of the record are read into the variable 
(or variables) until the physical length (or combined physical lengths) 
of parameterlist is exhausted, or until the end of the record is reached. 
(Required parameter) 
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USING BKREADBYKEY 

After calling BKREADBYKEY, you should always check the status parameter to determine 
whether the read was successful. Upon completion of BKREADBYKEY, the variables specified 
in parameterlist contain data read from the record located through the keyvalue and keylocation 
parameters. 

The key value in the record to be read must exactly match the specified keyvalue. Unlike BKSTART, 
the only relation between the value in the record and the value in the call is that of equality. If 
duplicate key values are allowed in the key being sought, then the first record with a matching key 
value is read by BKREADBYKEY. To read the remaining records with duplicate key values, you 
should use BKREAD. 



NOTE 

Each variable in parameterlist is filled to its current physical 
length before proceeding to the next variable. 

The example in figure 6-6 uses BKREADBYKEY to read the first record found with the value "23" 
starting in byte 2. Since this is the file written by BKWRITE in figure 6-11, the records in the file 
are identical including the keys and only the first record is read. 
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^220 REM «««»»«*»»»«»•»*»»«»»«»»»#«»•»«•»»»««»»«»#•»#»««»»##»«,,* 

32 30 REM » READ BY KEY FROM A KSAM FILE » 

2S<tQ REM <>«««««« »«««»•«•»••••««•«««» «•»«•»«««»»«•««••«*«•«••«••« 

2250 REM 

2260 REM F IS THE FILE NUMBE OF A KSAM FILE 

2270 REM OPENED BY A CALL TO BKOPEN 

2230 REM 

?29r> REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ 

23oO REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN IN THE 

2310 REM WRITE EXAMPLEt 

2320 REM 

2330 REM AN ADDITIONAL ASSUMPTION IS THAT THE DESIRt-0 KEY VALUE 

2340 REM STARTS AT CHARACTER 2 AND HAS THE VALUE "23". 

2350 REM 

2360 CALL BKREADBYKEY ( F i SS, "23" , 2 , Bl S , B2S , A5 C • 3 , A3 I • 3 , A2C • J ) 

2370 REM 

23»n REM NOW DETERMINE WHETHER THjS CALL HAS SUCCEEDED 

2390 REM 

2400 IF SSCU1 )<>"0" THtN DO 

2410 REM NS CONTAINS THE NAME OF THE KSAM FILE 

2420 REM S* CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 

2430 PRINT "UNABLE TO READByKEY •■ | NS | »' ERROR " I SSI 1 1 1 }| >« DETAIL "»SS[fc 

23 
24*0 CALL BKERROR(S$|M$) 
24S0 PRINT M$ 
2460 GOTO 3620 
2470 DOEND 
2480 REM 

2490 REM THE CONTENTS OF Bl$«"l", OF B2$«"23", 

25oo REM THE CONTENTS Of A5 1 1 ) THROUGH A5(5) ARE INTEGERS 1 THROUGH 5 
2510 REM THE CONTENTS OF A3 AND A? ARE UNKNOWN, 
2520 REM 

2530 REM ECHO WHAT WAS HEAD 
2540 REM 

2550 PRINT "RECORD READ a "|9i$|B2$ 
2560 MAT PRINT A5 
2562 MAT PRINT A3, A? 
2570 REM 
2580 REM THE PROGRAM CONTINUES 



Figure 6-6. Reading a Record Located by Key Value with BKREADBYKEY 
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Changes the contents of a record in a KSAM file. 

CALL BKREWRITE (fiknum, status, parameter list) 

li!|lp||l|t§lfl^ 

A call to BKREWRITE replaces the contents of an existing record with new values. The record to 
be rewritten is the last record accessed by a call to BKREAD, BKREADBYKEY, or BKSTART. To 
use BKREWRITE, the file must be open in the access mode that allows update. If access is shared, 
it must also be opened with dynamic locking allowed, and the file locked by BKLOCK before rec- 
ords are rewritten. 



PARAMETERS 

filenum 



status 



pararneterlist 



A numeric variable containing the file number that identifies the file; 
this number was returned by the last call to BKOPEN. It should not 
be altered unless the file is closed with a successful call to BKCLOSE. 
(Required parameter) 

A four-character string variable to which is returned a code that 
indicates whether or not the call to BKREWRITE was successful 
and if not, why not. The first character is set to zero if the call 
succeeds, to another value if not. (Refer to the Status Parameter 
discussion earlier in this section. 
(Required parameter) 

A list of variables or constants, separated by commas, that contain 
the data to be written to the file replacing the last record read or 
written. The total length of the new record is derived from the total 
number, data type, and length in characters of each item in 
pararneterlist. Although this length need not be the same as the 
record it replaces, it should be long enough to contain all the keys, 
but not so long that it exceeds the defined record length. 
(Required parameter) 



USING BKREWRITE 

After calling BKREWRITE, you should always check the status parameter to make sure that the 
rewrite was successful. Upon successful completion of BKREWRITE, new values replace the 
data in the last record read to or written from the BASIC program. The new data may change 
every value in the previously read record including the primary key value. 

If you want to replace a record with a particular key value, you should locate and read the record 
with BKREADBYKEY or BKSTART. To rewrite a series of records you should read the records 
with BKREAD. 

When the data in the pararneterlist of BKREWRITE is shorter in total length than the data in 
the record being rewritten, there is less total data in the rewritten record. In order to maintain 
the key sequence of all keys, defined values should be written to the location of all keys, both 
the primary key and any alternate keys. 
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NOTE 

Items written to a KSAM file with the BKREWRITE 
procedure are concatenated; rounding to word boundaries 
does not occur. 



The example in figure 6-7 writes new values to a record originally written if figure 6-11 and read in 
figure 6-5. The new values fill an array that had undefined values in the last five words, now defined 
as two arrays A3 and A2 by the BKREAD call. The primary key value "23" in location 2 is un- 
changed. 

The record read by BKREAD contained the following values: 



Primary Key 




12 3 4 5 



A5 



VL 



yi 



A3 A2 

(undefined) 



After being rewritten by BKREWRITE, it contains the following values: 




12 3 4 5 



12 3 



1 2 






A5 A3 A2 

B2$ (Primary Key) 



SHARED ACCESS. When access is shared, the call to BKREAD, BKREADBYKEY, or BKSTART 
that locates the record to be rewritten should be included in the same pair of BKLOCK/BKUNLOCK 
calls as the call to BKREWRITE. This insures that no other user alters the record pointer between 
the call that locates the record and the call that rewrites it. 

DUPLICATE KEYS. If you want to sequentially rewrite all records in a chain of records with du- 
plicate keys, locate the first record in the chain with BKREADBYKEY. Then call BKREWRITE to 
modify this record. If no key value (the selected key or any other) is modified, subsequent calls to 
BKREWRITE will modify the next sequential records in the chain of duplicate keys. If, however, 
any key has been changed, the modified key is written to the end of the chain and the next se- 
quential record is one with the next higher key value. In this case, to rewrite all records with du- 
plicate keys, precede each call to BKREWRITE by a call to BKREADBYKEY. 
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2600 RfcM 

2610 REM ea»«»»»»«»»«»**<>e»«*««»«fttt»««««<»«»»««tt«»«4>*«»«e««««»«««»» 

2620 REM * REVISE THE CONTENTS 0*" A RECORD READ FROM a KSAM FILE « 

26 30 REM #»»•»»»»•»•#•**»••**»•»•#•••*«*•»•••»*•»#•••»•*••»»••«*»• 

26^*0 REM 

2650 REM F IS THE FILE NUMBER OF A KSAM FILE OPENED BY A CALL TO BKOPEN 

2660 REM NOTE THAT FO« BKREWR j T E , BKOPEN ACCESS MODE MuSTs* F OR UPDATE. 

2670 REM 

2680 REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORO TO BE READ 

2690 REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN TO THE 

27 REM KSAM FILE IN THE BKWRITF EXAMPLEt, 

2710 REM ' — parameterhst 

2720 CALL «KREAD ( F , S$ » BIS , B2S , AS t # ] , A3 [ • ] , A2 t • ] ) 

2730 REM 

27*0 REM NOW DETERMINE WHETHER THE CALL HAS SUCCEEDED, 

2750 REM 

2760 IF SSCl»n<> H 0" THtN DO 

2770 REM N* CONTAINS THE NAME OF THE KSAM FILE 

2780 REM SS CONTAINS THE STATUS CALL SET BY THE PRECEDING CALL 

2790 PRINT "UNABLE TO READ >i|N*»» ERROR •' | SS C 1 t 1 1 I •• DETAIL "ISSC2) 

2800 CALL BKERROR(S$»Mn 

2S10 PRINT M$ 

2820 GOTO 3620 

2630 DOEND 

2900 REM THE CONTENTS OF BlSsl", OF B2$cii23it 

2910 REM THE CONTENTS Of; A5 (1 ) THROUGH AS(5) ARE 1 THROUGH 5 

2920 REM THE CONTENTS OF A3 AND A? ARE UNKNOWN 

2930 REM 

29*0 REM STORE VALUES 1 THROUGH 3 INTO A3 ( 1 ) THROUGH A3(3) 

2950 REM STORE VALUES 1 AND 2 INTO A2(j) AND A2<2). 

2960 REM 

2970 FOR Isl TO 2 

2980 A2CIJ=I 

2990 A3tIl*I 

3000 NEXT I 

3010 A3t3 3»3 parameterhst 

3020 REM / ' v 

3030 CALL BKREWRITE(F,S*,B1*,B2$,A5C»] ,A3C»J ,A2t«]) 

3040 REM 

30SO REM NOW DETERMINE WHETHER TH E CALL HAS SUCCEEDED 

3060 REM 

3070 IF S$(lU)O"0" THfcN 00 

30SO REM NS CONTAINS THE NAME OF THE KSAM FILE 

3090 REM SS CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 

3100 PRINT "UNABLE TO REWRITE "|NS|" ERROR "ISIlUlJI" DETAIL "ISSC2J 

3110 CALL BKERROR(SSiMi) 

3120 PRINT MS 

3130 GOTO 3620 

31*0 DOEND 

3150 REM 

3160 REM ECHO WHAT WAS UPDATED 

3170 REM 

3180 PRINT "REWRITTEN RfcCORD a "IB1IB2 

3190 MAT PRINT A5»A3|A2 

3200 REM 

3210 REM THE PROGRAM CONTINUES 



Figure 6-7. Rewriting Record in KSAM File with BKREWRITE 
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Positions a KSAM file to a particular record based on a key value. 



CALL BK.START{filenumMatus[,keyvalue[, keylocation [.relation ] ] ] ) 



By calling BKSTART, you can position the record pointer to any record in the file based on the 
value of a key in that record. The key can be the primary key or any alternate key, since BKSTART 
also allows you to select the key for positioning and for subsequent sequential reads. If you want 
to read all the keys in a key sequence, you can use BKSTART to position to the record with the 
lowest key value in the selected key 

PARAMETERS 



filenum 



status 



keyvalue 



keylocation 



relation 



A numeric variable containing the file number that identifies the file; 
this number was returned by the last call to BKOPEN. It should not 
be altered unless the file is closed with a successful call to BKCLOSE. 
(Required parameter) 

A four-character string variable to which is returned a code that indi- 
cates whether or not the call to BKSTART was successful and if not, 
why not. The first character is set to zero when the call succeeds, to 
another value when it fails. (Refer to the Status Parameter discussion 
earlier in this section.) 
(Required parameter) 

A string or numeric expression whose value is compared to a key value 
in this record. The record pointer is positioned to the first record with 
a key value that bears the relation specified by relation to the value 
in keyvalue. If the value is a string, its logical length is used for the 
comparison; otherwise, the physical or dimensioned length is used. The 
length of this value must be less than or equal to the length of the key 
as specified when the file was created. If keyvalue is a null string (" "), 
the file is positioned to the beginning of the first logical record accord- 
ing to the value of the key in keylocation. (Optional Parameter) 

Default: If omitted, the value assumed for keyvalue is the lowest 
value for the specified key type. 

A numeric expression whose value indicates the starting character loca- 
tion in each record of the key used for positioning by BKSTART. The 
characters in a record are counted starting with 1. If set to zero, the 
primary key is assumed. 
(Optional parameter) 

Default: If omitted, the primary key is assumed. 

A numeric expression whose value specifies the relation between the 
specified keyvalue and the value of the key at keylocation. The record 
pointer is positioned to the first record with a key value satisfying this 
relation: 

— the value of the record key is equal to keyvalue 

1 — the value of the record key is greater than keyvalue 

2 — the value of the record key is greater than or equal to 

keyvalue. (default) 
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Any value greater than 2 is treated as if it were 2. 
(Optional parameter) 

Default: If omitted, the relation is assumed to be 2, record key is 
greater than or equal to the keyvalue. 



USING BKSTART 



After calling BKSTART, you should check the status parameter to determine if the procedure was 
executed successfully. If successfully executed, the record pointer is positioned at the beginning 
of the first record with a value at keylocation that has the relation specified in relation to the value 
specified in keyvalue. 

If default values are assumed for all three optional parameters, the pointer is positioned to the 
record with the lowest value for its type in the primary key location. 

If the relation specified is equality (relation = 0), then a record must be located that has the exact 
same key value as that specified in the BKSTART call. When found, the pointer is positioned to 
that record. If duplicate values are allowed for the key, then the pointer is positioned at the first 
record with the particular key value. 

When the specified relation is greater than (relation = 1), the file is searched until a record is found 
with a key value greater than the specified key value. The search passes over any record with a key 
value equal to the specified value. This relation allows you to retrieve items by an approximate key. 
Thus, if you specify a key value of "R", a call to BKSTART will position the pointer to the first 
record with a key value that starts with the letter R. A subsequent series of calls to BKREAD 
allows you to read the remaining records in the file or, by including a test, to read only the records 
beginning with R. 

When the specified relation is greater than or equal to (relation = 2), BKSTART looks for a record 
containing a value equal to the specified value. If found, it positions the pointer to that record. If 
not found, it continues looking and positions the pointer to the first record that is greater than the 
specified value. This type of search can be used to locate records by generic key. A generic, or 
partial, key is a value that matches characters at the beginning of the key, but not necessarily the 
end. For example, in a key containing a date in the form yymmdd, by specifying only the first two 
characters as keyvalue and a relation = 2, you can position to the first record with a key for that 
year; by specifying the first four characters, you can position to the first record for a particular year 
and month. 

Whenever a record cannot be found with a key that satisfies the relation and value specified, the 
value "23" for invalid key is returned to status. 

BKSTART allows you to specify a key other than the primary key assumed by BKREAD. Called 
prior to a series of calls to BKREAD, it prepares for a sequential read of the file in alternate key 
order. For example, assuming a file with an alternate key in location 21, the following call positions 
the pointer to thp first record in that key sequence: 

100 DIM A$(10),S$(4) 

150 A$=" " -* ■ assign null string to keyvalue 

160 L = 21 -*— — alternate key location to keylocation 

170 CALL BKSTART(F,S$,A$,21) 
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The default for relation is 2 (greater than or equal to) and need not be specified except for docu- 
mentation purposes. 

Figure 6-8 illustrates the use of BKSTART with default values for all optional parameters. Speci- 
fied in this minimal form, it positions to the least valued primary key. 



l080 REM »***«»*»»»«»»««*«»»»»#»«»»«««»»»»o«»«»»«t»»##*#«»« # «« <><<><t 
1090 REM » POSITION TO LEAST VALUED PRIMARY KEY » 

ll0 fl REM •••*•••••••••*•••••«»*••••••»••••*««••»»•«*«*»««, ####4# 

1110 REM 

1120 REM F IS THE FILE NUMBER OF A KSAM FILE 

1130 REM OPENED BY A CALL TO BKOPEN 

11*0 REM 

1150 CALL P,KSTART(F,SS) 

1160 REM 

1170 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED 

1180 REM 

1190 IF S*tH13<> M 0" THEN DO 

1200 REM NS CONTAINS THE NAME OF THE KSAM FILE 

1210 REM S* CONTAINS THE STATUS CODE RETURNED BY THE PRECEDINQ CALL 

1220 PRINT "UNABLE TO POSITION FILE TO LEAST VALUED PRIMARY KEY" 

1230 PRINT "ERROR "|S*C1|13|<> DETAIL "|S$t21 

12«»0 CALL BKERROR(SSfMS) 

1250 PRINT MS 

1260 O0T0 3620 

1270 D0END 

12*0 REM 

1290 REM THE PROGRAM CONTINUES 

1300 REM 



Figure 6-8. Positioning Pointer to Least- Valued Record with BKSTART 

The example in figure 6-9 positions the record pointer to a record containing a specific key value. 
The value is "23"; it is located starting in the second character of each record. The value for relation 
is zero indicating that the key must contain exactly the value "23," not a value larger than "23." 
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1920 REM 

19 30 REM »»»««•«•••«»«••••••»««»•»••••••«»««•««•««*•»«•••«•••««« 

19*0 REM <t POSITION A KSAM FILE » 

1950 REM ««•**••«*»«••*•*••*•«»«•»•»•«••••»««••«••«*»»«»•«.«««««« 

1960 REM 

1970 REM F IS THE FILE NUMBER OF A KSAM FILE 

1980 REM OPENED BY A CALL TO BKOPEN 

1990 REM 

2000 REM AN ASSUMPTION HAS BEEN MADE THAT THE POSITIONING TO BE 

2010 REM DONE IS TO THE RECORD WRITTEN IN THE WRITE EXAMPLE, 

2020 REM ANO THAT THE DtSIRED KEY STARTS AT CHARACTER 2, 

2060 REM 

2070 CALL BKSTART(F,S$,"23»»2,0) 

2080 REM 

2090 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED 

2100 REM 

2110 IF SS[1I11<>"0" THtN DO 

2120 REM NS CONTAINS THE NA M £ OF THE KSAM FILE 

2130 REM S* CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL 

2l«0 PRINT "UNABLE TO START n|N$j" ERROR "|SS(l|l3|" DETAIL "|S*C2J 

2150 CALL BKERROR(SStMS) 

2160 PRINT M$ 

2170 GOTO 3620 

2180 DOEND 

2190 REM 

2200 REM THE PROGRAM CONTINUES 

2210 REM 



Figure 6-9. Positioning Pointer to Particular Record with BKSTART 
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Unlocks a file dynamically locked by BKLOCK 
CALL BKUNLOCK(filenum,status) 



A file locked by BKLOCK is released for use by other users with a call to BKUNLOCK. (If you log 
off from any connection with the system, the file is also unlocked.) Since dynamic locking takes 
place during shared access to the same file by more than one user, it is important that any file 
locked by BKLOCK be unlocked as soon as possible by BKUNLOCK. 

To use BKUNLOCK, the file must be opened with dynamic locking allowed by all users who share 
access to the file. 

PARAMETERS 

filenum A numeric variable containing the file number that identifies the file; 

this number was returned to filenum by the last call to BKOPEN. It 
should not be altered until the file is successfully closed by BKCLOSE. 
(Required parameter) 

status A four-character string variable to which is returned a code that indi- 

cates whether or not the call to BKLOCK was successful and if not, 
why not. The first character is set to zero when the call succeeds, to 
another value if it fails. (Refer to Status Parameter discussion earlier 
in this section.) 
(Required parameter) 

USING BKUNLOCK 

After calling BKUNLOCK, you should always check the status parameter to make sure that the 
procedure was successfully executed. When successful, a file locked by BKLOCK is again made 
available for access by other users. If the file is not locked by BKLOCK when BKUNLOCK is 
called, the file is not affected. 

Figure 6-10 illustrates the use of BKUNLOCK to unlock the file after it is updated. 
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171" REM « UNLOCK A KSAM FILE » 

l7<*0 REM #«»•»•••*•«••*•»•»«•••»•••••«••••••»••••••*•«*»••#••• 

173(1 PEM 

17*0 REM F IS THE FILE NUMBER OF A KSAM FILE 

17Sn REM OPENED BY A CALL TO BKOPEN 

1763 PEM 

1770 CALL «KUNLOCK(FiS*J 

1780 REM 

1790 PEM NOW DETERMINE WHETHER THE CALL HAS SUCCEEDtO 

leno REM 

1P10 IF S$tl»lJ<>"0» THtN DO 

le«?0 REM NS CONTAINS THE NAME OP THE KSAM FILE 

1830 REM S* CONTAINS THE STATUS CODE SET SV THE PRECEDING CALL 

18<»0 PRINT "UNABLE TO UNLOCK "IKSJ" ERROR "iSStllUl" DETAIL "»SS[2] 

1850 CALL 8KERR0R(S$.Ms» 

I860 PRINT MS 

1870 GOTO 3620 

1860 DOEND 

1890 PEM 

1900 REM THE PROGRAM CONTINUES 



Figure 6-10. Dynamically Unlocking a KSAM File 
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Retrieves the version, update number and fix number of the current KSAM/3000. 

CALL BK V »0 ESI ON (s ta tus, message) . 

A call to BKVERSION retrieves a printable string of characters that identifies the current version 
of the KSAM/3000 procedures used to process KSAM files. The string of characters returned by 
BKVERSION can be printed. 

PARAMETERS 

status A four-character string variable to which is returned the code that 

indicates whether or not the call to BKVERSION was successful and 
if not, why not. The first character is set to zero when the call succeeds, 
to another value if it fails. (Refer to the Status Parameter discussion 
earlier in this section.) 
(Required parameter) 

message A string variable to which is returned the identification of the current 

KSAM/3000 procedures. It is in the form: 

version, update.fix 

where version is an ASCII letter, update is an ASCII integer, and fix is 
also an ASCII integer. The three terms are separated by periods. 
(Required parameter) 

USING BKVERSION 

You may call BKVERSION in order to get the version, update, and fix numbers of the KSAM/3000 
currently being used. This identification can be compared to the version, update, and fix numbers 
that identify the version in which a KSAM file was created, as returned by the VERIFY command 
of program KSAMUTIL (refer to section II). The following example illustrates use of BKVERSION. 
Note that two strings are needed. 

10 DIM S$(4) -* status 

20 DIMV$(72)- message 



100 CALL BKVERSION(S$,V$) 

110 PRINT "THE CURRENT KSAM/3000 IS HP32208.";V$ 



RUN 

THE CURRENT KSAM/3000 IS HP32208.A.1.23 

contents of V$ 
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BKWRITE 

Writes data from a BASIC program to a KSAM file. 

CALL BKWRITE (filenum,status,parameterlist) 

A call to procedure BKWRITE writes a record to a KSAM file from a BASIC program. This call pro- 
vides the only way to create a KSAM record from a BASIC program. The file must have been opened 
with an access mode that allows writing. If access is shared, the file also must be opened for dynamic 
locking {lock = 1), and the file locked with BKLOCK before any records are written. 

PARAMETERS 

filenum A numeric variable containing the file number value that identifies 

the file; this number was returned by the last call to BKOPEN. It 
should not be altered unless the file is closed by a successful call to 
BKCLOSE. 
(Required parameter) 

status A four-character string variable to which is returned a code that 

indicates whether or not the call to BKWRITE was successful and if 
not, why not. The first character is set to zero when the call succeeds, 
to another value if not. (Refer to the Status Parameter discussion 
earlier in this section.) 
(Required parameter) 

parameterlist A list of variables or constants, separated by commas, that contain 

the data to be written to the file as a record. The total length of the 
record contents is derived from the total number, the type, and the 
length in characters of the items in parameterlist. The parameterlist 
must contain a value for each location defined as a key location in 
the record. 
(Required parameter) 

USING BKWRITE 

After calling BKWRITE, you should always check the status parameter to insure that the write 
was successful. Upon successful completion of BKWRITE, one record containing the values 
specified in parameterlist is written to the opened KSAM file. 

Two parameters that are set when the file is opened affect how BKWRITE operates. These are 
the access and sequence parameters. 

In order to write to a file, the file must be opened with access greater than 0. If the access 
parameter is set to 1, all existing data in the file is cleared before the first record is written to the 
file. If access is set to 2 or greater, the first record written by BKWRITE immediately follows 
any existing records; the file is not cleared. 

The sequence parameter determines whether records must be written in primary key sequence, 
or not. If sequence is zero, records can be written in any order; no check is made on the sequence 
of the primary key field. If sequence is set to 1, you must write each record with a value in the 
primary key field that is greater than the primary key value in the previous record. Primary key 
values may equal the previous primary key value only if the file was created with duplicate key 
values permitted. To illustrate, assume that the record illustrated by the following example was 
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the first record written to the file. It has the value 1 as its primary key. If the file was opened 
with sequence = 1 , the next record written must have a value of 2 or more in the primary key 
field. It may have the same value only if duplicates are allowed for that key field, and must not 
have a value less than the previous primary key. 

The values written to the record depend on the type of the items in parameterlist. To illustrate, 
consider the following statements: 

10 DIM D$(20),E$(10),S$(4) 
20 INTEGER I, J 

30 D$="MITCHELL" ■* logical length = 8 characters 

40 E$=" JAMES"- logical length = 5 characters 



50 1=0- 
60 J=l— 



■each integer requires 2 characters 




v r ' 



70 CALL BKWRITE (F,S$,I,J,D$,E$) 

filenum 

status 



parameterlist 



This set of statements writes one record to the KSAM file. The record has the form: 



characters 

1 3 5 13 18 80 







MITCHELL 



JAMES 



-i 1 — 1 

D$ E$ undefined value 



I J(key) 



Assuming a file created with one key starting in the third character, two characters long, the value 
1 is the key value. Each integer requires 2 characters, the two strings use a total of 13 characters, 
resulting in values that take up 17 characters of the record. The remainder of the record is 
undefined. Record size is specified at file creation. 

When writing from numeric arrays, the dimensioned length is used; when writing from strings 
the logical length is used. The logical length of a string variable or string array element, is the 
number of characters actually stored in the variable or element. It determines the length of the 
item written to the record. A numeric array, on the other hand, uses the dimensioned length as 
the length of the item written to the record. For example, suppose a numeric array A is added 
to the parameterlist in the previous example: 
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5 INTEGER A(10)- 

10 DIM D$(20),E$(10),S$(4) 
20 INTEGER I,J,F 
30 D$="MARSHALL" 
40 D$="MILLY" 
50 FOR 1=1 TO 5 s 
60 A(I)=1 
70 NEXT I 
80 1=0 
90 J=3 
100 CALL BKWRITE(F,S$,I,J,A(*),D$,E$) 



-dimensioned length of A is 10 words 



-Move 5 words to array A 



This set of statements results in a record with the following values: 

characters 

1 3 5 15 

3 | 1 2 3 4 5 







\ t ^ 
I J 
(key) 



array A 




-undefined values 



NOTE 

Items written to a KSAM file from a BASIC program are 
concatenated ; rounding to word boundaries does not 
occur. 



Figure 6-11 is an example of writing one string and one integer array to each record of the KSAM 
file opened in figure 6-4. The three records written contain the following data: 



B$ 

J- 



array A 



I 



key 
\ 



3[12 34 5 

t 



-record 1- 






123 



12 34 5 



_/V 



-record 2- 






123 



12 345 



^■v. 



record 3 



/ 



6-41 



BKWRITE 



10 DIM S*t4J 

SO DIM N«U2b] 

10 DIM MsC72] 

4 INTFGFK a [ I 1 

5 DIM '-! x [ 1 er ] 
SS INTFGF* J 
*>o DIM ri »[ 1 ] 
■sB DIM R?.»t2] 

70 INTFGF* A2C2) ,a3C3J , A5C5] 

Hi REM 

*0 REM THE KSAM/3O00 FILE Was ^UlLT WITH: 

loo REM R EC = -80, J«>,F .ASCII 

111 REM KEY«Bt2,2, » J UP 

1<?0 REM SO, RECORD LENGTH IS 2 BYTES, FIXED, TYPE ASCII, 16 REC/BLOCK. 

1 in REM THE KEY IS 2 CHARACTERS LONG , ST ART ING IN CHARACTER ? Or RECORD 

135 REM 



430 REM ••»»♦•*•••••#*•*••*•••*•••*•••••••••••»•••**•*••••#••••• 

440 REM « WHITE TO A KSAM FILE • 

45 REM »••##*•#*•#•••*••**••••#•»#••*•#•••••••»•*••*«•••••»•••* 

460 REM 

470 REM ASSIGN VALUES To OUTPUT VARIABLES 

480 REM 

490 FOR lal TO 5 

500 Atll'I 

510 NEXT I 

520 B$="123" 

530 REM 

540 REM F IS THE FILE NUMBER OF A KSAM FILE 

550 REM OPENED BY A CALL TO BKOPEN 

560 REM 



570 REM NOTE THAT ONLY THREE BYTES "123" ARE WRITTEN FROM BS 

580 REM WHEREAS TEN WOHDS ARE WRITTEN FROM NUMERIC" ARRAY A, 

620 REM 

630 REM THREE IDENTICAL RECORDS ARE BEING OUTPUT SO THAT 

640 REM SUBSEQUENT EXAMPLES OF THIS PROGRAM WILL EXECUTE 

650 REM 

660 FOR lal TO 3 

670 CALL BKwRITE(F,S*,B$iAt«l) 

680 REM 

690 REM NOW DETERMINt WHETHER THIS CALL SUCCEEDED 

700 REM 

71 6 IF S*U|13<>»0" THEN DO 

720 REM N$ CONTAINS THE NAME OF THE KSAM FILE 

730 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CODE 

740 PRINT "UNABLE TO WRItE To "|NS|»ERROR •> |SSt 1 | 1 ] | m DETAIL »|SSt», 

2) 

7S0 CALL BKERROR<S*,MS) 

760 PRINT MS 

770 GOTO 3620 

780 DOENO 

790 NEXT I 

800 REM 

810 REM THE PROGRAM CONTINUES 



Figure 6-11. Writing to a KSAM File with BKWRITE 
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ERROR MESSAGES AND 
RECOVERY PROCEDURES 



APPENDIX 



This appendix lists the error messages that may be issued as a result of errors encountered while 
accessing KSAM files. The messages are not limited to KSAM errors since other file system errors 
or language errors can occur while accessing a KSAM file. 

Whenever possible, the reason the message was issued is listed under "Meaning" and any action 
that can be taken to correct the error is listed under "Action." 

The messages are contained in the following tables: 

Table A-l File System Error Codes 

Table A- 2 COBOL Status Returns 

Table A-3 BASIC Status Returns 

Table A-4 KSAMUTIL Error Codes and Messages 

Table A-5 FCOPY Warning and Error Messages 
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Table A-l. File System Error Codes 



CODE 


MEANING 


ACTION 





END OF FILE 




1 


ILLEGAL DB REGISTER 




2 


ILLEGAL CAPABILITY 




3 


OMITTED PARAMETER 




4 


INCORRECTS REGISTER 




5 


PARAMETER ADDRESS VIOLATION 




6 


PARAMETER END ADDRESS VIOLATION 




7 


ILLEGAL PARAMETER 




8 


PARAMETER VALUE INVALID 




9 


INCORRECT Q REGISTER 




20 


INVALID OPERATION 




21 


DATA PARITY ERROR 




22 


SOFTWARE TIME-OUT 




23 


END OF TAPE 




24 


UNIT NOT READY 




25 


NOWRITE-RING ON TAPE 




26 


TRANSMISSION ERROR 




27 


I/O TIME-OUT 




28 


TIMING ERROR OR DATA OVERRUN 




29 


SIO FAILURE 




30 


UNIT FAILURE 




31 


END OF LINE 




32 


SOFTWARE ABORT 




33 


DATA LOST 




34 


UNIT NOT ON-LINE 




35 


DATA-SET NOT READY 




36 


INVALID DISC ADDRESS 




37 


INVALID MEMORY ADDRESS 




38 


TAPE PARITY ERROR 




39 


RECOVERED TAPE ERROR 




40 


OPERATION INCONSISTENT WITH ACCESS TYPE 




41 


OPERATION INCONSISTENT WITH RECORD TYPE 




42 


OPERATION INCONSISTENT WITH DEVICE TYPE 




43 


WRITE EXCEEDS RECORD SIZE 




44 


UPDATE AT RECORD ZERO 




45 


PRIVILEGED FILE VIOLATION 




46 


OUT OF DISC SPACE 




47 


I/O ERROR ON FILE LABEL 




48 


INVALID OPERATION DUE TO MULTIPLE FILE ACCESS 




49 


UNIMPLEMENTED FUNCTION 




50 


NONEXISTENT ACCOUNT 




51 


NONEXISTENT GROUP 




52 


NONEXISTENT PERMANENT FILE 




53 


NONEXISTENT TEMPORARY FILE 




54 


INVALID FILE REFERENCE 




55 


DEVICE UNAVAILABLE 




56 


INVALID DEVICE SPECIFICATION 




57 

.... 


OUT OF VIRTUAL MEMORY 
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Table A-l. File System Error Codes (continued) 



CODE 

58 

59 

60 

61 

62 

63 

64 

71 

72 

73 

80 

81 

82 

83 

84 

85 

86 

87 

89 

90 

91 

92 

93 

94 

100 

101 

102 

103 

104 

106 

107 

108 

110 

111 



MEANING 



112 

I 

169 



170 



171 

172 
173 
174 

175 



176 
177 



NO PASSED FILE 

STANDARD LABEL VIOLATION 

GLOBAL FUN UNAVAILABLE 

OUT OF GROUP DISC SPACE 

OUT OF ACCOUNT DISC SPACE 

USER LACKS NON-SHARABLE DEVICE CAPABILITY 

USER LACKS MULTI-RIN CAPABILITY 

TOO MANY FILES OPEN 

INVALID FILE NUMBER 

BOUNDS VIOLATION 

SPOOFLE SIZE EXCEEDS CONFIGURATION 

NO "SPOOL" CLASS IN SYSTEM 

INSUFFICIENT SPACE FOR SPOOFLE 

I/O ERROR ON SPOOFLE 

DEVICE UNAVAILABLE FOR SPOOFLE 

OPERATION INCONSISTENT WITH SPOOLING 

NONEXISTENT SPOOFLE 

BAD SPOOFLE BLOCK 

POWER FAILURE 

EXCLUSIVE VIOLATION: FILE BEING ACCESSED 

EXCLUSIVE VIOLATION: FILE ACCESSED EXCLUSIVELY 

LOCKWORD VIOLATION 

SECURITY VIOLATION 

USER IS NOT CREATOR 

DUPLICATE PERMANENT FILE NAME 

DUPLICATE TEMPORARY FILE NAME 

I/O ERROR ON DIRECTORY 

PERMANENT FILE DIRECTORY OVERFLOW 

TEMPORARY FILE DIRECTORY OVERFLOW 

EXTENT SIZE EXCEEDS MAXIMUM 

INSUFFICIENT SPACE FOR USER LABELS 

DEFECTIVE FILE LABEL ON DISC 

ATTEMPT TO SAVE PERMANENT Fl LE AS TEMPORARY 

USER LACKS SAVE FILE CAPABILITY 



ACTION 



RESERVED FOR FUTURE USE 



THE RECORD IS MARKED DELETED. FPOINT POSITIONED 
POINTER TO A RECORD THAT WAS MARKED FOR DELE- 
TION. 

DUPLICATE KEY VALUE WHEN DUPLICATES NOT 
ALLOWED. 

KEY NOT FOUND; NO SUCH KEY VALUE. 
tcount PARAMETER LARGER THAN RECORD SIZE. 
CANNOT GET EXTRA DATA SEGMENT FOR THIS FILE. 

KSAM INTERNAL ERROR. A KEY VALUE (NOT SEARCH 
KEY) FOR A RECORD TO BE DELETED IS NOT IN KEY 
FILE; RECORD CANNOT BE DELETED. 
ILLEGAL EXTRA DATA SEGMENT LENGTH. 
TOO MANY EXTRA DATA SEGMENTS FOR THIS 
PROCESS 
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Table A-l. File System Error Codes (continued) 



CODE 



178 
179 

180 



181 
182 
183 
184 

185 



186 



187 
188 
189 
190 
191 



192 



193 

I 

200 



201 

I 
255 



MEANING 



NOT ENOUGH VIRTUAL MEMORY FOR EXTRA DATA 

SEGMENT 

THE FILE MUST BE LOCKED BEFORE THIS INTRINSIC 

ISSUED 

THE KSAM FILE MUST BE REBUILT BECAUSE THIS 
VERSION OF KSAM DOES NOT HANDLE THE FILE 
BUILT BY PREVIOUS VERSION. 

INVALID KEY STARTING POSITION. 

FILE IS EMPTY. 

RECORD DOES NOT CONTAIN ALL THE KEYS. 

INVALID RECORD NUMBER IN FFINDN INTRINSIC; 

RECORD NUMBER IS NEGATIVE. 

SEQUENCE ERROR IN PRIMARY KEY; ATTEMPT TO 

WRITE RECORD WITH PRIMARY KEY LESS THAN 

PREVIOUS KEY WHEN ASCENDING SEQUENCE 

EXPECTED. 

INVALID KEY LENGTH. 



INVALID KEY SPECIFICATION; KEYS ILLEGAL. 
INVALID DEVICE SPECIFICATION. 
INVALID RECORD FORMAT. 
INVALID KEY BLOCKING FACTOR VALUE. 
RECORD DOES NOT CONTAIN SEARCH KEY FOR 
DELETION. SPECIFIED KEY VALUE POINTS TO 
RECORD WHICH DOES NOT CONTAIN THAT VALUE. 
SYSTEM FAILURE OCCURRED WHILE KSAM FILE 
WAS OPENED 



RESERVED FOR KSAM 



RESERVED FOR FUTURE USE 



ACTION 



INCREASE THE SIZE 
OF VIRTUAL MEMORY 
USE FLOCK TO LOCK 
FILE OR OPEN FILE FOR 
EXCLUSIVE ACCESS. 

USE FCOPYTO REBUILD 
FILE: 

>FROM=oldksamfi/e 
JO=(dfile,kfile) 



RECORD NUMBER MUST 
BE POSITIVE INTEGER. 



RUN KEYINFOOF 
KSAMUTILTO 
RESET FLAG. 
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Table A-2. COBOL Status Parameter Return Values 



STATUS 
VALUE 



"10" 



'21" 



"22" 



MEANING 



"00" SUCCESSFUL COMPLETION 

completed successfully. 



I/O operation was 



"02" SUCCESSFUL COMPLETION, DUPLICATE KEY 

Read or Readbykey read a record whose key value 
was the same as the equivalent key in the next 
sequential record; this is not an error since dupli- 
cate alternate keys are allowed. Write or rewrite 
operation was successful; a duplicate key was 
written for a key that is allowed duplicates. 



ACTION 



None. 



AT END - End-of-file or beginning-of-f ile reached 
during sequential or random read. There is no next 
logical record in ascending key order. 



INVALID KEY, SEQUENCE ERROR - Attempt 
was made to write a record with a primary key that 
is out of sequence when the file was opened for 
sequential access. 



INVALID KEY, DUPLICATE KEY - Attempt was 
made to write or rewrite a record with a key value 
that duplicates a key value in an existing record, 
and duplicates are not allowed. 



"23" INVALID KEY, NO RECORD FOUND - Attempt 

to access record identified by a key with CKSTART 
or CKREADBYKEY, but no record is found with 
the specified key value at the specified key location. 



None required, returned for informa- 
tion only. 



Usually none. This result is a signal 
to close the file or perform another 
end-of-file action. 



Check the primary key value in the 
record being written. If you don't 
want sequence checking, re-open the 
file for random or dynamic access. 



24" INVALID KEY, BOUNDARY VIOLATION - An 

attempt was made to write beyond the externally 
defined end of file. 



"30" LOCK DENIED - File was locked by another 

process. 



Check the key values. If possible 
change them to avoid the duplication. 
If duplicate keys must be written, 
create the file again allowing dupli- 
cates for the key and then copy the 
old file to the new file with FCOPY. 



Check the keyvalue, keylength, and 
keylocation parameters in the call. 
Correct if necessary. If record that 
cannot be found should be in the file, 
you may want to list the data file 
with FCOPY. 



Wait until process locking file unlocks 
it — try again or lock file with lockcond 

= 1. 
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Table A-2. COBOL Status Parameter Return Values (continued) 



STATUS 
VALUE 


MEANING 


ACTION 


"31" 


UNLOCK DENIED - File was not locked by call- 
ing process. 


Before calling CKUNLOCK to unlock a 
shared file it must have been locked by 
a call toCKLOCK. 


"9n" 


FILE SYSTEM ERROR - Where n is a binary 
number between and 255 corresponding to a 
File System Error code (Refer to table A-1 ). 


Within your program you can call 
CKERROR to convert the number to 
a displayable value and then display 
it. Look up the value in table A-1 and 
perform any suggested action. 



Note that COBOL error messages 752 and 753 are issued for errors processing KSAM files. (Refer to 
table C-2 in the COBOL manual.) 
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Table A-3. BASIC Status Parameter Return Values 



STATUS 
VALUE 


MEANING 


ACTION 


"00" 


SUCCESSFUL COMPLETION - The current I/O 
operation was completed successfully. 


None. 


"02" 


SUCCESSFUL COMPLETION, DUPLICATE KEY - 
In a call to BKREAD or BKREADBYKEY, the cur- 
rent key has the same value ps the equivalent key in 
the next sequential record; duplicate keys are al- 
lowed. Or in a call to BKWRITE or BKREWRITE, 
the record just written created a duplicate key value 
for at least one key for which duplicates are allowed. 


None required. Returned for informa- 
tion only. 


"10" 


AT END — A sequential read was attempted with 
BKREAD, but there was no next logical record in 
ascending sequence by key value, or random read 
attempted to position to record with key value less 
than lowest value or greater than greatest value. 


Usually none. This result is a signal to 
close the file or perform some other 
end-of-file function. 


"21" 


INVALID KEY, SEQUENCE ERROR - BKWRITE 
attempted; record being written has primary key 
that is not in sequential order but file was opened 
for sequence checking. 

BKREWRITE attempted, but the primary key 
value was changed since the record being re- 
written was read. 


Check the primary key value in the 
record; if you don't want sequence 
checking, reopen the file with 
sequence = 0. 

Check the primary key value. Either 
change it back to the original value 
or read the record again before calling 
BKREWRITE. 


"22" 


INVALID KEY, DUPLICATE KEY ERROR - 
BKWRITE or BKREWRITE attempted to write 
record that contains a duplicate value for a key 
that is not allowed duplicate values. 


Check the key value. If possible 
change it to a unique value. If 
duplicate keys must be written, 
create the file again allowing dupli- 
cate values for the key and then copy 
the old file to the new file. 


"23" 


INVALID KEY, NO RECORD FOUND - 
BKSTART or BKREADBYKEY attempted to 
locate a record by a key value that could not be 
found. 


Check the key value, and key location 
parameters. Correct if necessary. If 
record that cannot be found should be 
in file, you may want to list data file 
with FCOPY. 


-24" 


INVALID KEY, BOUNDARY VIOLATION - 
BKWRITE attempted to write beyond the ex- 
ternally defined boundaries of the file. 


Re-enter command. 


"71" 


REQUEST DENIED, FILE ALREADY LOCKED - 
BKLOCK was called with conditional locking and 
the file was already locked by another user. 


Perform some action that does not re- 
quire exclusive access and then try 
BKLOCK again. As soon as the other 
user unlocks the file BKLOCK will 
work. 
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Table A-3. BASIC Status Parameter Return Values (continued) 



STATUS 
VALUE 


MEANING 


ACTION 


"81" 


INVALID CALL, WRONG NUMBER OF PARAM- 
ETERS — A procedure call had too many or too 
few parameters. 


Check the call syntax and correct; if 
not sure of error, consult manual. 


"82" 


INVALID CALL, INVALID PARAMETER - 
Specified parameter is not the correct type. For 
example, a string variable was specified where only 
numeric variables or constants are allowed. 


Check the parameter and compare it 
to the rules specified in this manual 
for the parameter format. 


"83" 


INVALID CALL, INSUFFICIENT INTERNAL 
BUFFER SPACE - The data to be written to the 
file is too long for the configured internal buffer 
space. 


You can ask the system manager to 
reconfigure the system, or you may 
be able to reduce the amount of data 
being written from parameter/ ist. 


"9xxx" 


FILE SYSTEM ERROR - An MPE file system 
error occurred for which the value xxx specifies 
a 3-digit code between "0" and "255". 


Within your program you can call 
BKERROR to display a message with 
the meaning of the code; you can 
consult table A-1 for the code meaning. 
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Table A-4. KSAMUTIL Error Codes and Messages 



CODE 



MESSAGE 



1000 COMMAND FILE READ 
ERROR. 

1001 COMMAND FILE END OF 
FILE. 

1002 UNKNOWN COMMAND. TYPE 
HELP. 

1003 TOO MANY PARAMETERS 
FOR THIS COMMAND. 

1004 COMMAND FILE DATA 
TRANSMISSION ERROR. 

1005 COMMAND TOO LONG. 

1008 FILE NAME TOO LONG OR 

ABSENT. 



1007 'REC PARAMETER LIST 

EXHAUSTED. 



1008 'REC RECORD SIZE VALUE 

INVALID. 



1 009 ' R EC B LOC KING FACTO R 

VALUE INVALID. 



1010 'REC RECORD FORMAT 
VALUE INVALID. 

101 1 'REC RECORD TYPE VALUE 
INVALID. 



1012 'DEV DEVICE VALUE 
ABSENT. 

1013 'DEV DEVICE VALUE 
INVALID. 



MEANING 



Command name not recognized. 



More parameters specified than 
are allowed. 



File name in BUILD command 
incorrect. 



Too many parameters specified 
after REC= in BUI LD command. 



Record size in BUILD command 
is not valid. 

Block factor in BUILD 
command is not valid. 

Record format in BUILD 
command is not F or V. 

Record code in BUILD com- 
mand is not ASCII or 
BINARY. 

No device specification after 
DEV= in BUILD command. 

Device specification in BUI LD 
command is not valid. 



ACTION 



Type the correct name if 
you know it; else type 
HELP. 

Check the command syn- 
tax and reenter correctly. 



Enter file name of 8 or 
fewer alphanumeric char- 
acters starting with a letter. 

Check syntax and reenter 
with correct number of 
parameters. 

Check syntax and reenter 
with correct value for 
record size. 

Check syntax and reenter 
with correct value for 
blocking factor. 

Enter V for variable length 
records, F for fixed length, 
or omit for fixed length. 

Enter ASCII for ASCII- 
code records; BINARY or 
omit for binary-coded 
records. 

Enter legal device name or 
omit if device class is DISC. 

Enter legal device class 
name or legal logical device 
number. Refer to System 
Manager/System Supervisor 
Manual. 
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Table A-4. KSAMUTIL Error Codes and Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


1014 


'DEV DEVICE VALUE TOO 


DEV= missing device specifica- 


Enter device name that is 




LONG OR ABSENT. 


tion or one that is too long. 


1 to 8 alphanumeric char- 
acters, begins with a letter, 
terminates with non- 
alphanumeric character; 
or omit DEV= for DISC; 
or enter logical device 
number. 


1015 


'KEY' SPECIFICATIONS 


Too many KEY= specifications 


Reduce number of keys to 




EXCEED LIMIT. 


in BUILD. 


a total of 16. 


1016 


'KEY' CONTAINS TOO 


More than 5 parameters follow 


Parameters are: key type. 




MANY PARAMETERS. 


KEY= in BUILD. 


keylocation, keysize, and 
optionally, keyblocking, 
and DUP or DUPLICATE. 


1017 


'KEY' TYPE VALUE INVALID. 


Invalid key type specified after 


Key types may be: B, I, D, 






KEY= in BUILD. 


R, L, N, P,*. Enter one of 
correct types. 


1018 


'KEY' POSITION VALUE 


The key location is missing from 


Enter required keylocation 




ABSENT. 


KEY= in BUILD command. 


parameter following key- 
type in KEY= specification. 


1019 


'KEY' POSITION VALUE 


Invalid keylocation parameter 


Key location is specified as 




INVALID. 


specified after KEY= in BUILD. 


integer between 1 and num- 
ber of bytes in record. 


1020 


'KEY' SIZE VALUE RE- 


The key size is missing from 


Enter required keysize 




QUIRED AND ABSENT. 


KEY= in BUILD command. 


parameter after keylocation 
in KEY= specification. 


1021 


'KEY' SIZE VALUE INVALID. 


Invalid keysize parameter 


Key size is specified as the 






specified after KEY= in BUILD. 


number of bytes in the key; 
refer to table 2-2 for legal 
sizes for each key type. 


1022 


'KEY' BLOCKING FACTOR 


Invalid key blocking parameter 


Specify keyblocking as an 




VALUE INVALID. 


specified after KEY= in BUILD. 


even number equal to or 
greater than 4; or omit for 
key blocks with four keys 
per block. 


1023 


CONFLICTING OPTIONS 




Check command syntax 


1024 


MISSING CLOSING QUOTE 




Check command syntax 


1025 


'KEY"DUPLICATE' 


Key word DUP or DUPLICATE 


Enter DUP or DUPLICATE 




EXPECTED. 


expected in KEY= specification. 


or remove terminating 
commas. 
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Table A-4. KSAMUTIL Error Codes and Messages (continued) 



CODE 



MESSAGE 



MEANING 



ACTION 



1026 'DISC MUST BE FOLLOWED 

BY '='. 



1027 'DISC NUMBER OF 

RECORDS VALUE INVALID. 



1028 'DISC NUMBER OF EX- 

TENTS VALUE INVALID. 



1029 'DISC INITIAL ALLOCA- 

TION VALUE INVALID. 



1030 'LABELS' NOT FOLLOWED 
BY'='OR BY TOO MANY 
PARAMETERS. 

1031 'LABELS' NUMBER OF 
LABELS VALUE INVALID. 

1032 'FIRSTREC NOT FOLLOWED 
BY'='OR BY TOO MANY 
PARAMETERS. 



1033 'FIRSTREC STARTING 
RECORD NUMBER MUST BE 
0OR 1. 

1034 'CODE' NOT FOLLOWED BY 
'='OR BY TOO MANY 
PARAMETERS. 



1035 'CODE' FILE NUMBER 

VALUE INVALID. 



1036 'KEYDEV FOLLOWED BY 

TOO MANY PARAMETERS. 



Key word DISC in BUILD com- 
mand was specified without =. 



Value of numrecs parameter 
to DISC= not a positive integer. 



Value of numextents not in 
range 1-32. 



Value of initalloc not in range 
1-32. 



Key word LABELS in BUILD 
command was specified with- 
out = or had more than 1 
parameter. 



Keyword FIRSTREC in BUILD 
command was specified without 
= or had more than 1 parameter. 



Value other than or 1 entered 
for first record number. 



Key word CODE in BUILD 
command was specified with- 
out = or had more than one 
parameter. 

Value not in range through 
1023 entered for file code. 



Key word KEYDEV= in 
BUILD command was speci- 
fied with more than 1 
parameter. 



Reenter DISC= followed 
by up to 3 parameters 
describing disc file, or omit 
for defaults. 

Enter maximum number of 
records as file size, or omit 
for default value of 1023 
records. 

Enter integer between 1 
and 32, or omit for default 
value of 8 extents. 

Enter integer between 1 
and 32, or omit for default 
value of 1 extent allocated 
when file is opened. 

Reenter LABELS= followed 
by one parameter to specify 
number of user labels, or 
omit for default of 0. 



Reenter FIRST REC= fol- 
lowed by starting record 
number, or omit to start 
numbering records with 
zero. 

Enter correct value or omit 
for default of 0. 



Reenter CODE= followed 
by filecode, or om it for 
file code of zero. 



Enter positive integer 
between and 1023, or 
omit for default of 0. 

Reenter with one parameter 
to specify device class or 
logical device number of 
key file, or omit for DISC. 



A-10 



Table A-4. KSAMUTIL Error Codes and Messages (continued) 



CODE 



1037 



1038 



1039 



1040 



1041 



1042 



1043 



1044 



1045 



MESSAGE 



'KEYDEV MUST BE FOL- 
LOWED BY '='. 



'KEYDEV DEVICE PARAM- 
ETER VALUE TOO LONG 
OR ABSENT. 



'KEYFILE' NOT FOLLOWED 
BY '=' OR BY TOO MANY 
PARAMETERS. 



KEY FILE NAME TOO LONG 
OR ABSENT. 



'KEYENTRIES'NOT FOL- 
LOWED BY '=' OR BY TOO 
MANY PARAMETERS. 



'KEYENTRIES' NUMBER OF 
ENTRIES VALUE INVALID. 

KEYWORD SPECIFICATION 
IN THIS COMMAND IS IN- 
VALID. 



DELIMITER AT THE END 
OF A SPECIFICATION IS 
INVALID. 

THE NUMBER OF PARAM- 
ETERS IN THIS COMMAND 
IS INVALID. 



MEANING 



"Key word KEYDEV not followed 
by=. 



Key word KEYDEV= must be 
followed by valid device 
parameter. 



Key word KEYFILE in BUILD 
command was specified with- 
out = or had more than 1 
parameter. 

File name specified as KEY- 
FILE= parameter is more than 
8 characters or was omitted. 

Keyword KEYENTRIES in 
BUI LD command was specified 
without =, or had more than 1 
parameter. 



A key word specified as a 
KSAMUTIL command 
parameter is misspelled or 
not in syntax. 

A delimiter follows command 
specification in KSAMUTIL 
command. 

Too many or too few param- 
eters specified in a KSAMU1 L 
command. 



ACTION 



Reenter KEYDEV= or 
omit for default device 
class DISC. 

Reenter with device class 
specified as 1 to 8 alpha- 
numeric characters begin- 
ning with letter, terminated 
by non-alphanumeric char- 
acter, or reenter with logical 
device number, or omit for 
default DISC. 

Reenter KEYFILE= fol- 
lowed by actual file desig- 
nator of key file. 

Reenter KEYFILE= with 
correct file name format. 
(Refer to BUILD descrip- 
tion in manual.) 

Reenter KEYENTR I ES= 
followed by the maximum 
number of primary key 
entries expected in the key 
file, or omit for default 
of numrecs value from 
REC=parameter. 



Check command syntax for 
correct key word and/or 
spelling; reenter correctly. 

Remove delimiter or follow 
with rest of command. 

Check command syntax 
and reenter with the cor- 
rect number of parameters. 
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Table A-4. KSAMUTIL Error Codes and Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


1046 


A PARAMETER VALUE IS 


The key word TEMP was ex- 


Check command syntax, 




INVALID. 'TEMP' WAS 


pected as a parameter in 


reenter with correct 




EXPECTED. 


PURGE or RENAME 
commands. 


parameter value. 


1047 


LOCKWORD NOT 




Check command syntax; 




ALLOWED IN KEY FILE 




remove lockword from key 
file specification. 


1048 


GROUP AND/OR ACCOUNT 




Check command syntax of 




NOT ALLOWED FOR 




BUILD command. 




KEYFILE= 






1049 


BACK REFERENCE NOT 
ALLOWED ON formal- 
designator 






1050 


SEQ=SEQUENCE NUMBER 


Non-numeric sequence 


Check command syntax 




IS INVALID 


number specified for 


of KEYSEQ or KEYDUMP 






SEQ= parameter. 


commands. 


1051 


SUBSET= VALUE 


Either the starting 


Check command syntax of 




INVALID 


position or the number 

of key values to be dumped 

is invaled. 


KEYDUMP command 


1052 


SEQ= SYNTAX ERROR 




Check command syntax of 
KEYSEQ or KEYINFO 
command. 


1053 


SEQ= PARAMETER LIST 


Not enough information in 


Enter parameter value for 




EXHAUSTED 


parameter list; key 


SEQ=in KEYSEQ or 






number missing. 


KEYDUMP commands. 


1054 


FILE= PARAMETER 


Not enough information in 


Enter file name after 




LIST EXHAUSTED 


parameter list; file name 


FILE=in KEYDUMP 






missing. 


command. 


1055 


FILE= SYNTAX ERROR 




Check command syntax of 
KEYDUMP command. 


1056 


SUBSET= PARAMETER 


Not enough information in 


Check command syntax of 




LIST EXHAUSTED 


parameter list. 


KEYDUMP; enter correct 
number of parameters. 


1057 


SUBSET= SYNTAX ERROR 




Check command syntax of 
KEYDUMP command. 


1058 


INVALID KEY 


Key number specified in 


Key number is 1 for primary 




SEQUENCE 


SEQ= parameter is greater 


key, 2 for first alternate key. 




SPECIFICATION 


than the number of keys 


etc. Use VERIFY command 






in file. 


to check number of keys 
in file. 



A-12 



Table A-4. KSAMUTIL Error Codes and Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


1059 


FILE SPECIFIED 


File name specified in 


Enter name of non-existent 




IN FILE= ALREADY 


FILE= parameter is an 


file, or rename permanent file. 




EXISTS 


existing permanent file; 
KEYDUMP always creates 
a new file. 




1060 


B-TREE HAS MORE THAN 


KEYDUMP cannot dump more 






20 LEVELS 


than 20 levels of the key file 
structure. 




1061 


INVALID DECIMAL DIGIT 


Packed decimal digit is not 






OR DIGIT COUNT >28 


0-9, or there are more than 
28 digits. Cannot convert to 
ASCII for KEYDUMP 




1062 


THE REFERENCED FILE 


File reference in the 


Check file name and 




IS NOT A KSAM FILE 


command is not a KSAM file. 


correct it. 


1063 


RECORD SIZE OF THE 


Record size of the file 


Check KEYDUMP syntax; 




SPECIFIED FILE HAS 


specified in FILE= 


change : F 1 LE command so 




BEEN CHANGED 


parameter of KEYDUMP 


that record size is not 






has been changed by a 


specified. 






: F I LE command. 




1064 


GENERIC OR APPROXI- 


Generic or approximate 


Use full key value in 




MATE SEARCH NOT 


keys can be specified in 


SUBSET= or do not use 




ALLOWED FOR KEY 


SUBSET= parameter of 


SUBSET= parameter. 




TYPE 


KEYDUMP only if key 
type is BYTE, INTEGER, 
or DOUBLE. 




1065 


ILLEGAL OR TOO 


Position value of SUBSET= 


Change position value, or 




MANY CHARACTERS 


parameter in KEYDUMP 


use quoted string for 






contains non-numeric 


SUBSET= parameter. 






characters, or is >9 digits. 




1066 


REMOTE FILE ACCESS 


A : F I LE command specified 


Change :FI LE command 




NOT SUPPORTED 


a remote file, but this com- 
mand does not support 
remote access. 


to specify local file. 


1067 


SORT ON RECORD 


Sort of keydump by record 


Check the reasons for 




POINTERS FAILS 


pointers (SORT option of 


failure in SORT error 






KEYDUMP) failed during 


message. 






sort by SORT/3000 program. 




1068 


SYSTEM FAILURE 


KSAM file was open when a 


Run KEYINFO command 




OCCURRED WHILE 


system failure occurred, and 


to recover file and reset flag 




THE KSAM FILE WAS 


file may be damaged. 


so file can be opened, or run 




OPEN 




VERIFY with NOCHECK to 
examine file. 
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Table A-4. KSAMUTIL Error Codes and Messages (continued) 



CODE 



1069 



MESSAGE 



UNEXPECTED 
CHARACTER IN 
FILENAME; 
EXPECTED .or/ 



MEANING 



The only non-alphanu- 
meric characters allowed 
in a file name are "." or 



ACTION 



Check the file name 
and correct it. 



MAY 1981 
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Table A-5. 


FCOPY Warning and Error Messaj 


*es 


CODE 


MESSAGE 


MEANING 


ACTION 


None 


<CONTROL Y> 


Acknowledges receipt of a 
CONTROL-Y entered during 
a session. 


None. 


None 


READ ERROR FROM 


An error occurred while read- 


In a job: 




COMMAND IMPUTFILE 


ing an FCOPY command from 


Re-submit the job. 






SSTDIN. 


In a session: 








Re-enter the command. 


None 


WRITE ERROR TO COM- 


An error occurred while writ- 


More than likely nothing 




MAND LISTFILE 


ing an FCOPY message to 


serious has occurred and 






SSTDLIST. 


all FCOPY operations have 
been performed success- 
fully. If you want to be 
sure, however, do the 
following: 

In a job: 
Re-submit the job. 

In a session: 

Re-enter the most recent 

FCOPY command. 


3 


SYNTAX ERROR: IN 


The subset function was not 






SUBSET OPTION 


specified properly. 




4 


SYNTAX ERROR: IN 


The title option of the display 




TITLE OPTION 


function was not specified 
properly. 




5 


SYNTAX ERROR: IN 


The ignore errors function was 




IGNERR OPTION 


not specified properly. 




6 


SYNTAX ERROR: IN 


The verify function was not 




VERIFY OPTION 


specified properly. 


In a job: 

Correct the command and 

re-submit the job. 

In a session: 


7 


SYNTAX ERROR: IN 
SKIPEOF OPTION 


The skip end-of-file function 
was not specified properly. 


8 


SYNTAX ERROR: IN 


The compare function was not 




COMPARE OPTION 


specified properly. 


Re-enter the command 
using the correct format. 


9 


SYNTAX ERROR: IN 


The new file function was not 




NEW OPTION 


specified properly. 




10 


SYNTAX ERROR: IN 


The display hexadecimal func- 




HEX OPTION 


tion was not specified properly. 




11 


SYNTAX ERROR: IN 


The EBCDICOUT character 




EBCDICOUT OPTION 


translate function was not 
specified properly. 
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Table A-5. FCOPY Warning and Error Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


12 


SYNTAX ERROR: IN 
CHAR OPTION 


The display character function 
was not specified properly 


In a job: 

Correct the command and 

resubmit the job. 

In a session: 

Re-enter the command 

using the correct format. 


13 


SYNTAX ERROR: IN OCTAL 
OPTION 


The display octal function was 
not specified properly. 


14 


SYNTAX ERROR: IN UP- 
SHIFT OPTION 


The upshift function was not 
specified properly. 


15 


SYNTAX ERROR: IN 
BCDICIN OPTION 


The BCDICIN character trans- 
late was not specified properly. 


16 


SYNTAX ERROR: IN 
NORECNUM OPTION 


The NORECNUM option of 
the display function was not 
specified properly. 


17 


SYNTAX ERROR: IN 
EBCDICIN OPTION 


The EBCDICIN character trans- 
late function was not specified 
properly. 


18 


SYNTAX ERROR: IN 
BCDICOUT OPTION 


The BCDICOUT character 
translate function was not 
specified properly. 


19 


SYNTAX ERROR: IN- 
VALID FORM OF EXIT 
COMMAND 


The EXIT command was not 
specified properly. 


None. FCOPY terminates. 


51 


SYNTAX ERROR: IN 
QUOTED STRING 


The characterstring specified 
for the subset function is not 
valid. 


In a job: 

Correct the command and 

resubmit the job. 

In a session: 

Re-enter the command 

using the correct format. 


52 


SYNTAX ERROR: IN BIT 
PATTERN 


The patternlist specified for the 
subset function is not valid. 


53 


SYNTAX ERROR: IN- 
VALID INTEGER 


An integer specified is outside 
the range allowed for the 
particular FCOPY function. 


54 


SYNTAX ERROR: UN- 
KNOWN OPTION NAME 


One of the specified functions 
was unrecognizable. 


55 


SYNTAX ERROR: IN FROM- 
FILE SPECIFIER 


The "from" file was not speci- 
fied properly. 


56 


SYNTAX ERROR: IN 
TOFILE SPECIFIER 


The "to" file was not specified 
properly. 


57 


SYNTAX ERROR: ILLEGAL 
COMBINATION OF OPTIONS 


Two or more functionlist entries 
conflict with one another. 


58 


SYNTAX ERROR: FROM- 
FILE AND TOFILE NOT 
BOTH SPECIFIED 


FROM= and TO= were not both 
specified in the FCOPY 
command. 
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Table A-5. FCOPY Warning and Error Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


59 


SYNTAX ERROR: ILLEGAL 
USE OF NEW 


The context used to specify a 
new "to" file is not valid. 


In a job: 

Correct the command and 

resubmit the job. 

In a session: 

Re-enter the command 

using the correct format. 


60 


SYNTAX ERROR: ILLEGAL 
USE OF* 


The context used to specify* 
as a "from" file or "to" file 
is not valid. 


62 


SYNTAX ERROR: FILE 
NAME TOO LONG 


The "from" or "to" file name 
specified is longer than the 35 
characters allowed in a fully- 
qualified file name with 
lockword. 


102 


CAN'T CLOSE FROMFILE 


MPE can't close the "from" 
file. This message is followed 
by an MPE file information 
display containing (among 
other things) an error 
number. 


Look up the error number 
in table A-1 and act 
accordingly. 


103 


CANT CLOSE TOFILE 


MPE can't close the "to" file. 
This message is followed by an 
MPE file information display 
containing (among other 
things) an error number. 


104 


CANT SAVE NEW 
TOFILE 


MPE can't close the "to" file 
as a permanent file. Either 
you do not have SF capability 
or there is not enough group 
account, or system file space. 


If you don't have SF 
capability, you can't per- 
form the operation. 

If there is not enough file 
space, purge some un- 
needed files to free some 
file space. 


105 


CANT OPEN FROM FILE 


MPE can't open the "from" 
file. This message is followed 
by an MPE file information 
display containing (among 
other things) an error number. 


Look up the error number 
in table A-1 and act 
accordingly. 


106 


CANT OPEN TOFILE 


MPE can't open the "to" file. 
This message is followed by 
an MPE file information dis- 
play containing (among other 
things) an error number. 
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CODE 



107 



Table A- 5; FCOPY Warning and Error Messages (continued) 



MESSAGE 



VERIFY OR COMPARE 
OPTION: CAN'T GET 
READ ACCESS TO 
TOFILE 



108 ERROR IN CALLING 

FGETINFO FOR FROMFILE 



MEANING 



MPE can't get read access to 
the "to" file for a verify or 
compare operation. The read 
access specified in the file label 
has been overridden by an 
WIPE : FILE command contain- 
ing ACC=APPEND, ACCOUT, 
or ACCOUTKEEP. 



109 ERROR IN CALLING 

FGETINFOR FOR TOFILE 



110 IGNERR OPTION: 

FROMFILE NOT TAPE 



1 1 I CAN'T GET READ ACCESS 

TO FROMFILE 



112 CAN'T GET WRITE 

ACCESS TO TOFILE 



113 SKIPEOF OPTION: 

FROMFILE NOT TAPE 



114 SKIPEOF OPTION: 

TOFILE NOT TAPE 



An error prevented MPE from 
obtaining information from the 
"from" file's label. This mes- 
sage is followed by an MPE 
file information display contain- 
ing (among other things) an 
error number. 



ACTION 



Reset the particular :FILE 
command (using the MPE 
: RESET command) and 
retry the operation. 



An error prevented MPE from 
obtaining information from 
the "to" file's label. This mes- 
sage is followed by an MPE 
file information display contain- 
ing (among other things) an 
error number. 



The "from" file's device is not 
a magnetic tape unit. 



MPE can't get read access to 
the "from" file. The read access 
specified in the file label has 
been overridden by an MPE 
:FI LE command containing 
ACC=APPEND, ACC=OUT, 
or ACCOUTKEEP. 



MPE can't get write access to 
the "to" file. The write access 
specified in the file label has 
been overridden by an MPE 
:FILE command containing 
ACC=IN. 



Look up the error number 
in table A-1 and act 
accordingly. 



The ignore errors function 
cannot be used in this case. 



Reset the particular :FILE 
command (using the MPE 
:RESET command) and 
retry the operation. 



The skip end-of-file function 
was specified for the "from" 
file and the "from" file device 
is not a magnetic tape unit. 



The skip end-of-file function 
was specified for the "to" file 
and the "to" file device is not a 
magnetic tape unit. 



If the intended "from" or 
"to" file is on magnetic 
tape, check the associated 
MPE :FILE command and 
the back reference to it. 
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Table A-5. FCOPY Warning and Error Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


115 


SUBSET OPTION: STRING 


The characterstring ox pattern! ist 


Change the specified subset 




FALLS OUTSIDE OF 


specified is greater than the 


definition to a valid one 




FROMFILE RECSIZE 


record size of the "from" file. 
No such subset can exist in the 
specified "from" file. 


and try the operation again. 


116 


CAN'T GET LARGE 


There is not enough data space 


Ask the system manager 




ENOUGH BUFFER 


for the buffers needed by the 


what size data area was 






requested operation. FCOPY 


specified when FCOPY 






uses the DL-DB area for vari- 


was prepared and rerun 






able sized buffers. 


FCOPY specifying a larger 
MAXDATA= parameter. 

Also make sure that the 
system configuration will 
accommodate your record 
size in the maximum 
allowed data segment size. 


117 


SKIPEOF OPTION: ERROR 


An error occurred while 






WHILE SKIPPING IN 


skipping end-of-file marks 






FROMFILE 


in the "from" file. 




118 


SKIPEOF OPTION: ERROR 


An error occurred while 




WHILE SKIPPING IN 


skipping end-of-file marks 


Retry the operation. 




TOFILE 


in the "to" file. 




119 


SUBSET OPTION: ERROR 


An error occurred while 




WHILE SPACING IN 


spacing through the "from" 






FROMFILE 


file. 




120 


SUBSET OPTION: SUBSET 


The subset specified extends 


Change the specified subset 




STARTS OVER EOF 


over an end-of-file mark or a 


definition to a valid one 




BOUNDARY 


tape mark boundary. 


and try the operation again. 


123 


SUBSET OPTION: THIS 


The specified subset requires 


Check the MPE :FILE com- 




INPUT DEVICE DOES NOT 


backspacing in the "from" file 


mand associated with the 




BACKSPACE 


but the device for that file is 


"from" file and the back 






not a disc or magnetic tape. 


reference to it. 


124 


READ ERROR IN FROM- 


An error occurred while spac- 


Retry the operation. 




Fl LE AT RECORD recnum 


ing through the "from" file 
in search of the start of a 
subset. 




125 


SUBSET OPTION: NUMERIC 


A subset specified by starting- 


Change the specified subset 




SUBSET IS EMPTY 


record-number, number-of- 


definition to a valid one 






records, and/ 'or last-record- 


and try the operation again. 






number does not exist or 








contains no data. 
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Table A-5. FCOPY Warning and Error Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


126 


VERIFY OPTION: ERROR 
WHILE REWINDING 
FROMFILE 


An error occurred while spac- 
ing backward to the beginning 
of the "from" file at the start 
of a verify operation. 


Retry the operation. 


127 


VERIFY OPTION: ERROR 
WHILE REWINDING 
TOFILE 


An error occurred while spac- 
ing backward to the beginning 
of the "to" file at the start of 
a verify operation. 


Retry the operation. 


128 


EOF FOUND WHILE 
SPACING IN FROMFILE 


An end-of-file mark was en- 
countered while spacing 
through the "from" file in 
search of the start of a sub- 
set. This most often occurs 
when the "from" file is a 
blocked magnetic tape. For 
a blocked magnetic tape, the 
record numbers supplied in 
the SUBSET= parameter are 
used as block numbers. 


Retry the operation specify- 
ing block numbers instead 
of record numbers. 

OR 

Reblock the tape so each 
block contains one record 
and then retry the 
operation. 


129 


EOF FOUND WHILE 
SPACING IN TOFILE 


An end-of-file mark was en- 
countered while spacing 
through the "to" file in 
search of the start of a sub- 
set during a compare or 
verify operation 


Compare operation: 
The "from" and "to" files 
are not identical. Display 
the "to" file to determine 
what it actually contains. 

Verify operation: 
The copy operation was 
not performed correctly. 
Retry the operation. 


131 


ERROR WHILE WRITING 
EOF TO TOFILE 


An error occurred while 
writing an end-of-file mark 
in the "to" file. 


Retry the operation 


132 


VERIFY OPTION: ERROR 
WHILE SPACING IN THE 
FROMFILE 


An error occurred while 
spacing through the "from" 
file during a verify 
operation. 


133 


VERIFY OPTION: ERROR 
WHILE SPACING IN THE 
TOFILE 


An error occurred while 
spacing through the "to" 
file during a verify 
operation. 
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Table A-5. FCOPY Warning and Error Messages (continued) 



CODE 


MESSAGE 


MEANING 


ACTION 


134 


WARNING: FOUND EOF 


FCOPY has performed the 


The "to" file was not 




INTOFILE 


specified operation but has 


large enough. Use the 






filled the "to" file before 


MPE:LISTF/7/e/7a/7?e,2 






completing the operation. 


command to determine 
the "to" file's size and 
then increase its size (using 
the MPE :PURGE and 
:BUILD commands) and 
retry the operation. 


135 


WRITE ERROR TO 


An error occurred while 


Retry the operation. 




TOFILE 


writing to the "to" file. 




136 


READ ERROR FROM 


An error occurred while read- 


Compare operation: 




TOFILE 


ing from the "to" file during 


Retry the operation. If 






a compare or verify operation. 


the error persists, you 
must try to recreate the 
"to" file. 

Verify operation: 
Retry the operation. 


137 


WARNING: AN UNLABELLED 


An operation involving a mag- 


This is not an error. You 




TAPE OPERATION ENDS ON 


netic tape "from" file was 


can avoid this message by 




AN ERROR 


terminated by reading beyond 


reading the "from" tape 






the end of valid data rather 


one file at a time and using 






than by sensing an end-of-file 


the keyword SUBSET. 






mark. 
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TITLE OPTION: TITLE TOO 


The title specified for the list 


In a job: 




LONG 


function is longer than the 70 


Correct the command and 






characters allowed or it ex- 


resubmit the job. 






tended over more than one line 
(record). 


In a session: 

Re-enter the command 

using the correct format. 


139 


DUMP OPTION: TOFILE 


A file display was directed to 


Change the record size of 




RECSIZE NOT WITHIN 


an intermediate storage device 


the intermediate storage 




LEGAL LIMIT 


with an incorrect record size. 


file (using the MPE 






That record size must be > 60 


:PURGEand:BUILD 






bytes (30 words). 


commands) so that it is 
within the allowed range 
and then retry the oper- 
ation. 
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Table A- 5. FCOPY Warning and Error Messages (con 


tinued) 


CODE 


MESSAGE 


MEANING 


ACTION 


140 


COMPARE OR VERIFY 


The compare or verify operation 


Compare operation: 




OPTION: OPERATION 


was not attempted because the 


None. The compare oper- 




FAILS; DIFFERENT 


record sizes of the "to" and 


ation revealed that the 




FIXED RECSIZES 


"from" files are not identical. 


fixed record sizes of the 
two files are not identical. 

Verify operation: 
Change the record size of 
the "to" file (using the 
MPE :PURGEand :BUILD 
commands) so that it is 
the same as that of the 
"from" file and then retry 
the operation. 


141 


COMPARE BEGINS 


The comparison phase of a 
verify operation has begun. 


None. 


143 


WARNING: FROMFILE IS 


The "from" file contained 


None. You may have acci- 




EMPTY 


no data. Nothing was copied 


dentally specified the 






or compared. 


wrong file as the "from" 
file. 


144 


NEW OPTION: FILE 


The "to" file named for the 


Change the name of the 




ALREADY EXISTS 


new file function already exists 


"to" file and try the oper- 






in the specified (or implied} 


ation again. 






group and account. 




145 


BACKSPACE ERROR IN 


An error occurred while spacing 


Retry the operation. 




FROMFILE 


backward to the beginning of 
the "from" file or a subset 
within it. 




200 


WARNING: FROMFILE 


The record sizes of the "from" 


In a job: 




RECSIZE IS number type, 


and "to" files are not identical. 


FCOPY performs the speci- 




TOFILE RECSIZE IS 




fied operation despite the 




number type 




conflict. 

In a session: 

You are given the choice 
whether or not to continue 
the operation. 

Note that if the "from" 
record size is larger than 
the "to" record size, the 
"from" records would be 
truncated. If the "to" 
record size is larger than 
the "from" record size, the 
content of the excess byte 
positions in the "to" 
records is unpredictable. 
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Table A-5. FCOPY Warning and Error Messages (continued) 


CODE 


MESSAGE 


MEANING 


ACTION 


201 


WARNING: FROMFILE IS 
ASCII, TOFILE IS BINARY 

or 
WARNING: FROMFILE IS 
BINARY, TOFILE IS ASCII 


The data formats of the "from" 
and "to" files are not identical. 


In a job: 

FCOPY performs the oper- 
ation despite the conflict. 

In a session: 

You are given the choice 
whether or not to continue 
the operation. 


301 


READ ERROR IN 
FROMFILE AT RECORD 
recnum 


An error occurred while read- 
ing from the "from" file at 
the record number displayed 
(recnum). 


Retry the operation. If 
the error persists, use the 
subset function to copy 
all of the file except the 
erroneous record. 


302 


VERIFY OPTION: RAN 
OUT OF VERIFY ERRORS 
AT FROMFILE RECORD 
recnum 


The verify function was 
terminated because the speci- 
fied maximum number of 
errors has been exceeded at 
the record number displayed 
[recnum). 


Retry the operation specify- 
ing a larger number-of- 
errors parameter. 


304 


COMPARE OPTION: RAN 
OUT OF COMPARE ERRORS 
AT FROMFILE RECORD 
recnum 


The compare function was 
terminated because the speci- 
fied maximum number of 
errors has been exceeded at 
the record number displayed 
(recnum). 


Retry the operation specify- 
ing a larger number-of- 
errors parameter 


901 


KSAM FROMFILE 
BOUNDARY (EOF OR BOF) 


The beginning or end of the 
from file was reached during 
the copy operation. 




902 


KSAM FROMFILE 
POSITIONING ERROR 


Could not position to desired 
place. 


Try again. 


903 


ERROR; WRONG CONDI- 
TIONS FOR OPENING 
NEW KSAM FILE 




From file is not a KSAM 
file, or NOKSAM was 
specified. 


Create a KSAM file before 
running FCOPY and copy 
to that file. 
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KSAM/3000 INTERNAL 
STRUCTURE AND TECHNIQUES 



APPENDIX 



B 



OVERVIEW 



KSAM files can be used efficiently without any knowledge of how the files are structured or how 
file blocking and size is determined. The default values provided for file capacity, key blocking, num- 
ber of key entries, and so forth are effective in many applications. This appendix provides the sophis- 
ticated programming staff with information on how KSAM files are structured, how disc space is 
allocated to a KSAM file, and how memory space is allocated for the Extra Data Segments used when 
a KSAM file is modified or accessed. Such information may be useful for improving performance 
based on the particular application. 



KSAM FILE STRUCTURE 



A KSAM/3000 file is two physical files: a data file and a key file. The data file portion of a KSAM 
file contains all the data in the file and contains nothing but the data. Data records are written to the 
data file in the order in which they are received from a program. (The last record added is always 
written to the end of the file.) This chronological order is not necessarily in sequence by key value. 
At the time the file is opened, you can specify that records must be written in primary key sequence, 
but the default mode is to write records in any order. 

The key file portion of a KSAM file contains the key entries that maintain the sequence of the data 
records. As a data record is written to the data file, a key entry is added for each key defined for the 
file, and the sequential connections between key entries maintained. This means that if there is a pri- 
mary key and two alternate keys, three key entries are added with each new data record, and three 
sets of pointers are updated to reflect the new key sequence of each key. 

The structure of the data file is like that of any MPE file. Data records may be fixed or variable in 
length. If fixed, each record is the size specified when the file is created (default size is equivalent to 
one 128-word disc sector). If variable, the actual size of each record is included in the record itself, 
and the maximum size of any record is used to determine the blocking. By default, data records are 
blocked one record per block. 

The structure of the key file is more complex. The key file is organized so that locating a particular 
key requires the least number of accesses. For this purpose, the key files are organized in a particular 
structure known as a "B-Tree" 1 B-tree structure has two main advantages: 

• The number of file accesses is limited to the number of levels in the tree. If there are two levels, 
no more than two reads of the key file are needed to locate a particular key. 

• The key file is balanced. This means that each level pointer associated with a particular key value 
points to approximately as many higher key values as lower key values at the next level of the 
tree. 

B-tree structure in general is discussed below, followed by a discussion of how KSAM key files use 
this structure. 



Described in "Organization and Maintenance of Large Ordered Indexes", Bayer and McCreight, Acta Informatica, Springer Verlag 
1972, pp 173-189. 
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B-TREE STRUCTURE 

In a B-tree, there is always one root level block that points to blocks at a lower level. At the lowest 
level, the blocks are called leaves and they do not reference another level. In a two-level structure (see 
figure B-l), the blocks at the second level are all "leaves". If the tree has more than two levels, inter- 
mediate blocks (nodes or branches) are referenced by a higher level and themselves reference a lower 
level. Unless this lower level is a leaf, it also references a lower level. This continues until the lowest 
(leaf) level is reached. 

The notion of higher and lower level does not refer to the key values. The root block key values are 
always central and point to blocks with lower values and blocks with higher values. Thus if there are 
two entries at the root or a branch level, there will be three pointers to the next level: one for key 
values less than the first key value, one for key values less than the second key value but greater than 
the first, and one for key values greater than the second. 

Within each block, values are stored in ascending order. Although not all blocks are filled with values, 
each block in a tree is the same size. Figure B-l illustrates a simple 2-level tree with one root block 
and three leaf blocks. The root is a single block and each leaf is a block of the same size. (This example 
uses the KSAM minimum key block size consisting of four key entries per block.) 
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Figure B-l. Two-Level B-Tree Structure 



ADDING OR DELETING KEYS. When a key block is full and new keys are added, the root level 
block may need to be split, causing a new root block to be introduced and adding a new level to the 
tree. This process is illustrated in figure B-2 where the addition of one new key to a partially filled 
block does not affect the tree structure, but the addition of a second key to the full block causes 
the block to split. 
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Again, this example assumes the minimum key block size for the sake of simplicity. Note that all 
key file maintenance is performed in the KSAM extra data segment where space is allocated for one 
more key than the key block size. This allows the addition of a key to a "full" block. Before the 
block is read back into the key file, it is split so that the key block size is maintained. 
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Figure B-2. Split Causes New Level in Tree 



When the root block and all the leaves are full, another split becomes necessary. Figure B-3 illustrates 
a split caused when a new key is added to a full two-level tree structure, forcing it to a three-level 
structure. 
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Figure B-3. Tree Growth from Two to Three Levels 



Note that key blocks must always be defined with an even number of keys. As a result, when a key 
is added to a full block, there will be a middle value to form a block at a new level. This maintains 
the balance essential to B-tree structure. 

As records are deleted from the data file, two blocks at the same level (brothers) may be merged into 
one block. If sufficient records are deleted, the root block may be merged into a higher level, thereby 
contracting the number of levels in the key structure. 
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KSAM KEY FILE STRUCTURE 

A KSAM key file consists of three types of information: 

• Control — contains general control information such as the KSAM file name, and 

the number of keys defined for the file. 

• Key descriptor — contains general key information for each key such as the starting loca- 

tion in the data record of the key field, and the location in the key file 
of the root key entry. 

• Key entries — Each key entry contains information about a key associated with a data 

record. This information consists of: 

• the key value 

• a pointer into a data record in the data file with the same key value. 

• pointers into other records within the key file. 

The control and key descriptor information is contained in two blocks (physical records) at the be- 
ginning of each file. Regardless of the number of keys in the file, each block is 128 words (1 sector) 
long. Thus, every key file is preceded by two sectors of control and key descriptor information. 

The key entries are also organized into blocks of a fixed size. However, the exact number of blocks 
and the size of each block is based on a variety of factors, such as the key size, the number of keys 
in the file, the number of key values for each key, the key blocking factor, and so forth. (Calculation 
of key block size is discussed later in this section.) These key entry blocks are organized into the B- 
tree structure discussed above. A separate key structure is maintained for each key defined for the 
file. Thus there may be up to 16 separate tree structures in a single KSAM file. 

Refer to figure B-4 for a simplified diagram of a KSAM key file with two keys each organized into 
a two level tree structure. For a detailed description of the three types of block, refer to figures B-5 
and B-6. 

CONTROL BLOCK. This 128- word block contains information on the data file associated with the 
key file, and keeps track of the number and type of access to the key file. It also specifies the number 
of keys (primary and alternate) defined for the KSAM file. The name of the data file and the number 
of keys are essential for associating the key file with the data file. The number of keys determines 
how many entries are in the Key Descriptor Block. (Refer to figure B-5.) 

KEY DESCRIPTOR BLOCK. This 128-word block contains one 8-word entry for each key defined 
for the KSAM file. The first entry describes the primary key, the next entry describes the first al- 
ternate key (if there is one), and each subsequent entry describes any additional alternate keys. The 
first word of each entry points to the root block for that key; another important item is the location 
of the key in the data file record. (Refer to figure B-5.) 
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CONTROL BLOCK (first block in each key file) 
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Key Block Read Counter 



Key Block Write Counter 



Key Block Split Counter 
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Figure B-5. Control Block and Key Descriptor Block 
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KEY ENTRY BLOCKS. Each block in the key file contains, in addition to the key values, pointers 
that link the key blocks to each other and pointers that link each key value to an associated data 
record. Preceding these entries, the first item in every key block is the address of the block on disc; 
the next item is the number of keys in the key block. 

All key block access for search and modification is performed in the KSAM extra data segment. 
The disc address in each key block insures that the block is returned to its correct location on disc 
from the extra data segment. 

Figure B-6 illustrates the general layout of all key entry blocks. Each key value is followed by a 
pointer to a data record and a pointer to the block at the next level with higher key values. The first 
pointer in each block points to a block at the next level with lower key values. These pointers are set 
to zero for key blocks that have no next level (the leaves on a tree structure). 
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Figure B-6. Key Entry Block Structure 
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RELATION OF KEY TO DATA FILE 

The purpose of the KSAM key file is to maintain the order of data records in the data file. In order 
to maintain sequential order for each key, the keys blocks are connected through pointers. In addition 
to these pointers, each key entry must also contain a pointer linking the key value to the data record 
containing the corresponding key value. 

When the KSAM file is created, each key is defined by its starting location in the data record, its 
length, and its type. The location is specified as the character position where the key value starts; 
the length is the maximum number of characters used by the key value; its type is the type of the 
value such as, an integer, a character string, or a double-word integer. 

Thus, if the primary key is defined as a character string that starts in character position 3 and is 20 
characters long, then KSAM expects that each data record will contain such a value in that location. 
Whatever is placed in the defined location is treated as the primary key and determines the order in 
which data records are sequenced. 

The order in which records are physically written to the date file is called chronological sequence. 
This sequence may or may not also be a key sequence. If the records were written to the file in pri- 
mary key sequence, then this sequence and the chronological sequence are the same. If there is an 
alternate key for the file, however, it is very unlikely that alternate key sequence is the same as the 
chronological sequence. 

NOTE 

Key sequence in KSAM files is always in ascending order by 
key value. 

Refer to figure B-7 for a simplified diagram of the relation between the primary keys in the key file 
and the associated data records in the data file. (A similar diagram could be set up for the alternate 
key.) The diagram shows the pointer in each key entry pointing directly to a record in the data file. 

When a data record is to be located by key value, the root block for the appropriate key is searched 
first, using a binary search method. If the key is in the root block, the search is over. If it is not, the 
key value is between two root block values or it is less than the lowest value or greater than the 
highest. Using the pointer in the appropriate location, a block at the next level is located. This block 
is then searched for the selected key. Again, if the key is found, the search is over. If the key is not 
found at this level, the appropriate pointer to the next level is used and the search continues. 

When the selected key value is found, the pointer to the data file associated with that key value is 
used to locate the record in the data file. 
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KSAM FILE SIZE 



The size of the data file is calculated from the maximum number of data records times the size of 
each record (for fixed length records). For variable length records, it is calculated from the maximum 
number of data blocks times the size of each block. By default, a KSAM data file contains 1024 rec- 
ords (or blocks) in which each record (or block) is 1024 words long. This default size fits each block 
into eight disc sectors (each sector is 128 words long), and results in a data file of 8192 sectors. 

Calculation of key file size is more complex. It is based on the total number of keys in the file (pri- 
mary and alternate), the size of each key entry (including overhead), the expected number of data 
records specified when the file is built, plus space to allow for block splitting when the number of 
key entries increases. 

The number of key entries per key is usually exactly the same as the number of data records expected. 
By default, KSAM uses the maximum number of data records specified, or the default value of 1024 
records. This number is multiplied by each key in addition to the primary key to arrive at the total 
number of key entries in the file. 

The size of each key entry and the number of key entries per block (the blocking factor) is used to 
determine key block size. Since all blocks in the key file must be the same size, KSAM adjusts the 
blocking factor so that all keys, regardless of entry size, use the same block size. Also, this blocking 
factor may be adjusted so that disc sector space is not wasted. (A block always starts on a sector 
boundary.) By default, the blocking factor is adjusted so that a block size of 1024 words is used for 
all key blocks for all keys in the file. 

Because of the nature of the B-tree structure, enough room must be left in the key file so that the 
file can be increased in a balanced manner. When block splitting occurs as a result of adding new key 
values, up to half of each key block may have empty slots. To allow for such expansion, the key file 
size is calculated, and then doubled. 

The following discussion describes exactly how KSAM calculates the key block size, and then the 
total key file size. These calculations are useful primarily if you do not use default values for the key 
blocking factor and for the number of key entries. In such a case, they may help you determine the 
most effective block size and file size for your application. 

KEY BLOCK SIZE 

Key block size can affect the complexity of the tree structure and this complexity can affect access 
time. In order to understand the relation between block size and access time, consider the following 
general rules: 

• The larger the block, the less often it has to split and the fewer the splits, the fewer levels to 
the tree. 

• The more levels to the tree, the more mass storage retrieval time is needed to locate a particular 
key value. 

From this it would follow that in order to reduce access time, you should define large blocks. This 
is true only up to a point. Depending on the total number of key values expected in the file, a large 
block size may result in a great deal of unused space in each block. Also, the blocking factor may 
result in unused disc space since all blocks must start on sector boundaries. 
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KSAM provides a default blocking factor that produces a block with 1024 (IK) words. This size has 
proved to be efficient for many files. You may, however, override this default blocking by specifying 
a value in the key blocking parameter of the ;KEY= option in the BUILD command, or in word 19 
of the FOPEN ksamparam parameter. Note that any blocking factor you specify is a minimum value 
since KSAM may increase the blocking factor so that the least amount of disc space is wasted. 

After creating a KSAM file, you can use the VERIFY command of KSAMUTIL to determine the 
number of levels needed by the KSAM file. The VERIFY listing will also tell you the actual blocking 
factor used in creating the file so you can find out whether your specified blocking factor has been 
increased. 

CALCULATING KEY BLOCK SIZE. Key block size is based on a number of factors: 

• The key size is bytes (KS) 

• The key entry size in words (ES). 

• The number of key entries per block, the blocking factor (BF). 

Once the block size is determined, the number of sectors needed to hold one block is calculated. If 
this value (NB) wastes sector space, KSAM adjusts the blocking factor to produce a block size that 
uses the least number of sectors by filling each sector as completely as possible. Note that when KSAM 
uses the default block size of 1024, it calculates a blocking factor by the same method. 

The following steps show how KSAM determines block size based on a specified minimum blocking 
factor. 

NOTE 

The notation I I means round down the result of the enclosed 

algorithm to the next whole number; I I means round it up. 

1. Calculate the entry size (ES) in words from the key size (KS) in bytes, and then add two words 
for each pointer in the key entry (see figure B-6). KSAM uses the following algorithm to per- 
form this calculation: 

ES = L (KS+l)/2 J + 4 

2. If the blocking factor (BF) was specified as an odd number, KSAM issues an error message. 
Otherwise, it uses the specified blocking factor to continue the calculation of block size. 

3. Determine block size (BS) by multiplying the key entry size by the blocking factor and adding 
5 words. (The five words are for the three words of control information at the beginning of 
each block, plus two words for the final pointer in the block. See figure B-6). KSAM uses the 
algorithm: 

BS = (ES x BF) + 5 

Since blocks always start on sector boundaries, this calculated block size may leave a lot of unused 
sector space. The following steps show how KSAM determines the most efficient block size and, if 
this size differs from the size calculated from the specified blocking factor, how KSAM adjusts this 
blocking factor upwards to produce the optimum block size. 
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4. Determine the number of sectors required to hold the block at its calculated size. If the result 
is not a whole number, round it up to the nearest whole sector. KSAM determines the number 
of sectors per block (NB) as follows: 

NB = r BS/128 1 

5. Multiply the number of sectors per block by 128 to determine the optimum block size: 

BS = NB x 128 

6. If the optimum block size calculated in step 5 differs from the block size calculated in step 3, 
or if the default block size 1024 is used, KSAM adjusts the blocking factor to one that produces 
the optimum block size. It uses the following algorithm to determine the number of key entries 
that fit in the block and, if this is an odd number, reduces it by one. (Blocking factor must be 
an even number.) 

BF = T ( L (BS-5)/ES J -l)/2 1x2 

KEY FILE SIZE 

KSAM uses the blocking factor and the number of sectors per block to determine the maximum file 
size in sectors to allocate to the key file. In addition, KSAM needs to know the maximum number 
of key entries to expect, and the number of keys (primary and alternate) defined for the key file at 
creation. 

The maximum number of key entries for each key may be specified in the numentries parameter of 
the KEYENTRIES= option of the BUILD command, or in the ksamparam parameter of FOPEN. 
However, this file limit is usually based on the maximum number of data records. This value is spe- 
cified in the numrec parameter of the DISC= option of the BUILD command, or in the filesize 
parameter of FOPEN. If not specified in either of these places, KSAM assumes a default file limit 
of 1024 key entries. 

Since the number of records in the data file can be used to calculate the maximum number of keys 
for only one key, each additional key defined for the file causes the file sizes to be summed. 

When key file size has been calculated, KSAM uses this value to allocate that number of sectors on 
disc to the key file whenever the file is opened. 

Key file size is based on the following factors: 

• The number of key entries per block, or the blocking factor (BF). 

• The number of blocks per sector (NB). 

• The maximum number of key entries for one key (FL). 

• The number of keys defined for the key file. 

KSAM uses the following formula to determine key file size in sectors for a file with one key: 
FS = ( r FL/BF 1 x 2) x NB 
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This formula is derived through the following steps: 

1. The maximum number of key entries (FL) is divided by the number of key entries per block 
(BF) to find the number of blocks in the file. If not a whole number, it is rounded up to include 
all blocks. 

2. The resulting number of blocks is multiplied by 2. This doubling of the number of key blocks 

is done to allow room for expansion when the number of levels in a key file expands due to block 
splitting. 

3. Finally, the number of blocks is multiplied by the number of blocks per sector (NB) to find the 
total number of sectors needed to contain all key entries. 

NOTE 

The file size (FS) calculated by the above algorithm does not 
include the two sectors required for control information. 

If the file has only one key, add 2 to the file size (FS+2) to get the total file size. The value 2 repre- 
sents the two sectors at the beginning of each key file containing control and key descriptor informa- 
tion. 

If the key file has multiple keys, then the optimum block size of each key must be determined. The 
largest block size is then selected as the standard block size for all keys in the file (KSAM does not 
allow variable-length key blocks). Since the block size of some keys has changed, the blocking factor 
(BF) must be recalculated for these keys using the algorithm: 

BF = T ( L (BS-5)/ES J - l)/2 1x2 

A separate file size for each key is then calculated based on their various blocking factors. The total 
key file size is equal to the sum of all these file size (FS) values plus 2 for the two control sectors. 

Figure B-8 summarizes the steps KSAM uses to calculate file size for one key. Figure B-9 shows how 
KSAM calculates key file size for a file with two keys. Each key file size (FS) is calculated separately, 
and then the blocking factor and file size of the key with the smaller block size is recalculated. 

For a file with one key, KSAM simply adds 2 sectors to the file size (FS) calculated for the single key. 
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KS = key size in bytes 

ES = key entry size in words 

BF = blocking factor (number of key entries per block) 

BS = key block size 

FL = data file limit in records 

NB = number of sectors per key block 

FS = key file size in sectors 

r~l = roundup |_J = round down 



BS=1024 
(default) 



ES= L(KS+ D/2J+4 ■* 2 words/pointer 



fewest # words that contain key entry 



BF specified? 
Y 



BF = even number? 
Y 



BS=(ESXBF) + 5 •*- 



NB= TBS/1281 
I t_ 



■* error 



3 control words + 2-word pointer 



# words in sector 



BS = NBx 128 *- 



■optimum block size 



-+ BF = r(L(BS-5) /ESJ-1)/2"lx2 *- 



adjusted BF 



# key entries in block 

s 



rounded to nearest even whole # 



FL specified? 



Y 



FL= 1024 (default) 



FS = (rFL/BFH x2)xNB 



-double # of blocks for block splitting 



Figure B-8. Formula to Determine File Space per Key 
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Assume a file with 2 keys defined as: 



KEY = B, 1,53,1 2 
KEY = B,54,13,20 



For Key 1 : 

KS=53 

FL=1024 (default) 

BF=12 

Calculation of FS: 

ES= L(53+1) /2J+4 = 27+4 = 31 
BS=(31x12)+5=377 
NB=r377/128~l=r2.9> 3 sectors 
BS=3x128 = 384 
*BF= r(L(384-5)/31J-1)/2lx2 

= ~"(L12.2J-1)/21x2 

= T{ 12-11/21x2 

= T5.51x2 = 6x2 = 12 
FS=(T1 024/1 21 x2)x3 

=(T85.3lx2)x3 

= 516 sectors 



For Key 2: 

KS=13 

FL= 1024 (default) 

BF=20 



ES=L(13+1)/2J+4 = 7+4 = 11 
BS= (11x20)+5=225 
NB= T225/1 281 = l~1 .751 = 2 sectors 
BS= 2x128 = 256 
*BF=r(L{256-5)/1lJ-1)/2lx2 

= r(L22.8J-1)/2lx2 

= r(22-1)/21x2 

= T1 0.51x2= 11x2 = 22 
FS=(n024/221x2) x2 

=(T46.51x2)x2 

= 188 sectors 



Since key 1 has the largest block size (384 words in 3 sectors), its blocking factor is unchanged. The blocking 
factor for key 2 is adjusted so it has the same block size. The following values are used: 



ES=11«— 
BS=384 •«- 



FL=1024«- 
NB=3« 



entry size calculated for key 2 

■ block size of key 1 (now used for key 2, also) 

■ default file size in words 

• number of sectors needed for each block of 384 words 



Calculate the new blocking factor for key 2: 

*BF= H L (384-5/1 U -1 ) /21 x2 
= r(L34.4J-1)/2"1x2 
= T16.5lx2= 17x2=34 

FS=( T 1 024/341 x2)x3 

=( l~30.11 x2) x3 = 186 sectors 

Summing the two file sizes and adding two sectors for control and key descriptor information, the total file 
size in sectors is: 

516 + 186 + 2 = 704 sectors 

*The algorithm to calculate BF can be expressed more simply if the result can be checked for an even 
number: 

BF=LBS-5/ES J If BF is an odd number, set BF=BF-1 



Figure B-9. Calculation of Total Key File Size with Two Keys 
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KSAM EXTRA DATA SEGMENTS 



Another factor that may affect performance when KSAM files are used, is the number and size of 
KSAM extra data segments. An extra data segment (XDS) is an area in memory used as a buffer during 
KSAM file access. Each extra data segment contains: 

Statistical information on file use (listed by VERIFY command); 

Control Block and Key Descriptor Block data from the first two sectors of each KSAM key file; 

A Working Storage area large enough to hold a data record and two key entries; 

A data block buffer large enough to hold a block from the data file; 

At least one, and up to 20, key block buffers each large enough to hold one key block. 

When the key file is searched for a particular data record, the root block and lower level blocks, as 
needed, are moved to key block buffers in the extra data segment. Key entries are compared in the 
working storage area. When the data block is located, it is moved to the data block buffer of the extra 
data segment, and when the particular data record is located, it is moved to the working storage area. 

Since each open KSAM file is allocated an extra data segment and each extra data segment can be up 
to 32K words long (32,767 words), KSAM files can use a lot of memory. When there is not enough 
room in memory for all the extra data segments, they must be swapped between memory and disc 
as needed. This swapping can slow access to KSAM files. 

In order to minimize swapping, you can reduce the number of KSAM files by combining several files 
into one file. This automatically reduces the number of extra data segments, and it can be a very 
effective way to improve performance, particularly when files are shared by a number of users. (Refer 
to Number of Extra Data Segments, below.) 

Decreasing the overall size of the extra data segment may reduce swapping of extra data segments. 
However, reducing the number of key block buffers in the extra data segment may increase swapping 
of key blocks between the key file and the extra segment during a file search. By default, KSAM 
allocates key block buffers according to a formula that takes into account the type of access for 
which the file is opened, the number of levels in the key file structure, and the number of alternate 
keys in the file. Since this formula (see table B-l) keeps the extra data segment size as small 
as is compatible with efficiency, the default number of key block buffers should be used except in 
special cases. (For details, refer to Extra Data Segment Size later in this section.) 

NUMBER OF EXTRA DATA SEGMENTS 

KSAM assigns an extra data segment to each KSAM file opened by an active process. Since more 
than one process can use the same file during shared access, one file may require a number of extra 
data segments. Thus, the number of extra data segments depends both on the number of KSAM 
files and the number of users concurrently using the file. (Refer to figure B-10.) 
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Figure B-10. Extra Data Segments for Shared Access 

EXTRA DATA SEGMENT SIZE 

The size of each extra data segment associated with an open KSAM file is determined by the number 
of key block buffers it contains, the size of each key block buffer, the size of the data block buffer, 
and to a lesser extent, the key entry size and the data record size. (Refer to figure B-ll.) 

Initially (when a file is opened), 12K words are allocated to the extra data segment. If less actual 
space is needed, the extra space is not used, but remains in virtual memory. If more is needed, 
the original extra data segment is released and a new extra data segment is allocated with the 
actual size needed. 

The maximum size of any extra data segment is 32K words. The actual size is calculated from: 

• The total size of the overhead statistics and working storage area; 

• The size of the data block buffer; 

• The size of each key block buffer and the number of buffers allocated. 



B-18 



The overhead statistics and working storage area is approximately 1V2K bytes long depending on 
variables such as the key entry size and the data entry size. The data block buffer size is based on 
the size of each data block in the data file. Each key block buffer must be large enough to contain 
all the key entries in a key block plus one key entry used when new keys are added to a full block 
(as described earlier, see figure B-2). 

The default key block size is 2K bytes (1024 words) and the maximum size of the key block buffer 
is 4K bytes (2048 words). If a key block is larger than 4K bytes, KSAM reduces the block size so 
that no block is larger than will fit in an extra data segment key buffer. Thus, the main variable in 
extra data segment size is the lumber of key block buffers. 



KSAM 
Extra Data Segment 



Data used 
by VERIFY 



Current data record, 

& key comparison area 



Current data block 



1 key block per buffer 



STATISTICS 
CONTROL BLOCK 

& 

KEY DESCRIPTOR 

BLOCK 



Working Storage 



Data Block 
Buffer 



Key Block 
Buffer 



Key Block 
Buffer 



up to 20 

Key Block 

Buffers 



> A (approx. V/2K bytes) 



/ 

) 



B (maximum 4K words) 



> C # of key block buffers 
x key block buffer size 
(maximum size per block 
=4K bytes) 



Total Extra Data Segment size = A + B + C (maximum 32K words) 



Figure B-ll. KSAM Extra Data Segment 
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NUMBER OF KEY BLOCK BUFFERS. The number of key block buffers depends on the type of 
access for which the file is opened, the number of keys in the file, and the number of levels in the 
tree structure for each key. (Refer to table B-l for details.) The least number of buffers is allocated 
for read only access, unless the primary key has many levels in its structure. More buffers are usually 
required for write only, read/write, or update access. The number of buffers for read only access 
increases with the number of levels used by the key, but is never less than one. The number 
of buffers for write only access increases with the number of alternate keys in the file, but is never 
less than six. The number of buffers for all other types of access increases with the number of alter- 
nate keys and with the number of levels for each key, but is never less than four. 

Unless you specify a particular number of key block buffers, KSAM allocates buffers in the extra 
data segment according to the file characteristics as shown in table B-l. 

Table B-l. Number of Key Block Buffers Assigned by Default 



Access Type 


Buffers Assigned 


Read Only Access 


1 buffer per level in key with most levels 
(minimum of 1 buffer up to 20 buffers) 


Write Only Access 


3 buffers per primary key + 3 buffers per alternate key + 3 buffers 
(minimum of 3 buffers up to 20 buffers) 


Other Access 

(Read/Writeor 

Update) 


1 buffer per level in + 1 buffer per level + 3 buffers 
primary key structure in alternate key structure 

(minimum of 3 buffers up to a maximum of 20 buffers) 



Note that you can determine the number of levels per key with the KSAMUTIL command, VERIFY. 

For example, if the file is opened for read only, and the only key needs two levels, two key block 
buffers are allocated. If the file is opened for write only, and there is one alternate key in the file, 
nine key block buffers are allocated. If this same file is opened for update access, the primary key 
uses two levels, and the alternate uses three, a total of eight buffers is allocated. 

If you want to override the number of key block buffers assigned by default, you can use the MPE 
:FILE command before opening the file, or set the numbuffers parameter of FOPEN when you open 
the file programmatically. 

The file equation is specified as follows: 

:FILE filename; DE V=,,#buffers 

The KSAM extra data segment will be allocated space for as many key block buffers as you specify, 
up to a maximum of 20. (Note that the third DEV= parameter is interpreted as the number of key 
block buffers only when the file name is a KSAM file; for standard MPE files, this parameter indicates 
the number of list copies of the file.) 

Another way to reduce the number of key block buffers is to use fewer alternate keys, or to adjust 
the blocking factor so that the key file structure uses fewer levels. Either of these methods is effective 
when the file is written to or updated more than it is simply read. 
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Note that when you are loading a KSAM file with large amounts of data, you should increase the 
number of key buffers. The more key buffers in the extra data segment, the more likely it is that, 
as new data is added, locations for the new key values will be found in memory. This cuts down on 
disc access and can significantly reduce the time it takes to load the file. 

For example, if you are reloading a KSAM file after a system failure, you should use the :FILE 
command to increase the number of buffers to maximum of 20 buffers. Then, after the file is 
loaded, you can allow it to revert to the default number of buffers established by KSAM for the 
particular file. 

EXTRA DATA SEGMENTS WITH SHARED ACCESS 

The extra data segment allocated to each open file acts as a control block for that file. The extra 
data segment contains not only the current data block and the current key block buffers, but also 
the latest control information for the file. This information includes the logical and chronological 
record pointers that indicate the current record being accessed. Because the current pointer posi- 
tion is not in a "common block", when several programs open the same file, each can alter the key 
file structure by adding or deleting records so that the pointers set by other programs may point 
to the wrong record without those other programs being aware of it. 

To make sure that the latest pointer position is stored with the file rather than in the separate 
extra data segments, programs that share the same KSAM file must use a locking scheme. When- 
ever a program locks a KSAM file, the control information is transferred from the file to the extra 
data segment; and when a program unlocks the file, the contents of the extra data segment is writ- 
ten back to the file. Thus, each program should lock a KSAM file before executing any procedure 
that positions a record pointer (pointer-independent procedures), and not unlock the file until all 
procedures that depend on this pointer position (pointer-dependent procedures) have completed 
execution. This is true regardless of whether the pointer is chronological (points to a record in the 
data file) or is logical (points to a key in the key file). Both types of pointer are maintained in the 
extra data segment for the open file. 

Table B-2 lists all the procedures that affect or are affected by the record pointers. 



B-21 



Table B-2. Pointer Dependence 



Pointer-Independent 
Procedures 


Pointer 
Type 


Pointer-Dependent 
Procedures 


Pointer 
Type 


FFINDBYKEY 
CKSTART 
BKSTART 


Logical 


FREAD 
CKREAD 
BKREAD 


Logical 


FFINDN 


Logical 


FSPACE 


Logical 


FREADBYKEY 
CKREADBYKEY 
BKREADBYKEY 


Logical 


FREMOVE 
CKDELETE 
BKDELETE 


Logical 


FWRITE 
CKWRITE 
BKWRITE 


Logical 


FUPDATE 
CKREWRITE 
BKREWRITE 


Logical 


FPOINT 


Chronological 


FREADC 


Chronological 


FREADDIR 


Chronological* 


* Each procedure that sets the logical pointer also sets the chronological pointer; 
the logical pointer as well as the chronological pointer. 


but only FPOINT sets 



The pointer-independent calls position the pointer regardless of its current position. Pointer-de- 
pendent calls, on the other hand, must know to which record the pointer is currently positioned 
in order to operate correctly. 

All the procedures listed in table B-2 affect the pointer in some way. In order to use these pro- 
cedures correctly, it is important to understand how each moves the pointer, whether it positions 
the pointer directly or advances it from its current position. 

In general, when access to the file is random, the pointer is positioned directly. For example, a 
call to FFINDBYKEY (or CKSTART or BKSTART) positions the logical pointer to a particular 
key in the key file based on a key value specified in the call; and a call to FPOINT positions the 
chronological pointer to a particular record determined by its chronological record number. 

When access to a file is sequential or the file is being modified, pointer positioning is not direct but 
is relative to its previous position. Depending on the sequence in which procedures are executed, 
the pointer may or may not be advanced to the next record in key or chronological sequence. 
Internally, a flag is used to indicate whether or not to advance the pointer. This flag, the "Do Not 
Advance" flag, is set to FALSE if the pointer is to be advanced sequentially, to TRUE if it is not 
to be advanced. Some procedures never test the flag; these are, in general, the pointer-independent 
procedures that set the pointer directly. Other procedures test the flag and advance the pointer if 
the flag is FALSE; generally, these are procedures that read the file or position the pointer sequen- 
tially. Table B-3 summarizes when the pointer is set or advanced. (Note that only SPL procedures 
are listed; check table B-2 for the equivalent BASIC or COBOL procedures.) 
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Table B-3. Record Pointer Summary 



Beginning of Call 


Procedure 


End of Call 


Check 
DNA Flag 


Record 
Pointer 


Record 
Pointer 


Sets 
DNA Flag 


- 


- 


FFINDBYKEY 


Position 


TRUE 


- 


- 


FFINDN 


Position 


TRUE 


- 


Position 


FREADBYKEY 


- 


FALSE 


- 


- 


FWRITE 


Advance 


TRUE 


If TRUE 
If FALSE 


Advance 


FREAD 


- 


FALSE 


If TRUE 
If FALSE 


Advance 


FSPACE 


Position 


TRUE 


- 


- 


FREMOVE 


Advance 


TRUE 






FUPDATE 

(key value 
changed) 


Advance 


FALSE 
TRUE 


- 


- 


FPOINT 


Position 


TRUE 


- 


Position 


FREADDIR 


- 


FALSE 


If TRUE 
If FALSE 


Advance 


FREADC 


— 


FALSE 


Advance: Move logical pointer to next record in key sequence or move chronological 

pointer to next record in chronological sequence. 
Position: Set pointer to record specified in call. 



For example, if you call FREADBYKEY, it positions the pointer to a specified key value. After the 
call, the logical pointer remains positioned to this key and the Do Not Advance flag is set to FALSE. 
If the next call is to FREAD, FSPACE, or FREADC, then the pointer is advanced to the next key 
in key sequence before these procedures perform their other functions. Thus, after FREADBYKEY, 
a call toFREAD will read the next record, not reread the same record, and a call to FSPACE will 
move the pointer relative to the record following the record just read. 
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ASCII CHARACTER SET IN 
COLLATING SEQUENCE 



APPENDIX 



In the collating sequence for ASCII characters, unlike EBCDIC, numbers precede letters. 

Table C-l. ASCII Characters in Sequence 



DECIMAL 
VALUE 


CONTROL/ 
GRAPHIC 


COMMENTS 


DECIMAL 

VALUE 


CONTROL/ 
GRAPHIC 


COMMENTS 





NUL @ c 


Null 


'11 


Jill 


jC 


wHBM^^^KpJijSlif 


1 


SOH A c 


Start of heading 


42 


tpliislli 


i c 


Asterisk 


2 


STX B c 


Start of text 


43 


+ 


k c 


Plus sign 


3 


ETX C c 


End of text 


44 


liilfifitipjlMl 


i l " 


Comma 


4 


EOT D c 


End of transmission 


4 b 


Iflll 


m c 


Minus sign (hyphen) 


5 


ENQ E c 


Enquiry 


46 




n c 


Decimal point (period) 


6 


ACK F c 


Acknowledge 


47 




o c 


Slash 


7 
8 


BEL G c 
BS H c 


Bell 
Backspace 








• : 










9 


HT l c 


Horizontal tabulation 


'-8 





P c 


li^^^BiS^l^ftittJifii^ifcliKiiSi 


10 


LF J c 


Line feed 


49 


flpl 


q c 


One 


11 


VT K c 


Vertical tabulation 


50 


2 


r c 


• wo 


12 


FF L c 


Form feed 


51 


3 


s c 


Ihreo 


13 


CR M c 


Carriage return 


52 


4 


t c 


Foui 


14 


SO N c 


Shift out 


53 


5 


u c 


^^^^^8BBrt!D^jB^^piiii^|^fcj^pi 


15 


SI O c 


Shift in 


54 


6 


v c 


Six 








filiillM?iil 


7 


,■/■ 


Sftvfin ; 


16 


DLE P c 


Data link escape 


515 


8 


x c 


IpittislJiiiiBB^ 


17 


DC1 Q c 


Device control 1 (X-ON) 


67 


■j 


yC 


Nirtfe 


18 


DC2 R c 


Device control 2 


-.-$&•■" 


lllllil 


>■:&:■:. 


S^^^Kl^MBBlipl^i^ 


19 


DC3 S c 


Device control 3 (X-OFF) 


" 59 / 


lii|||M|Pj; 


: fc : • ; 


SemicoJoo 


20 


DC4 T c 


Device control 4 


fo 


< 


|c 


ii^^HMifciiBlSftjillS 


21 


NAK U c 


Negative acknowledge 


61 


|!ipi|i 


) c 


|^Mi|W^pifplijiiiM| 


22 


SYN V c 


Synchronous idle 


62 


• ?* 


^c 


iiiM^s^wSpiftlili^P 


23 


ETB W c 


End of transmission block 


B3 -,.;■;■ 


. f ; 


pEL c , 


Question mark. 


24 
25 


CAN X c 
EM Y c 


Cancel 

End of medium 


















26 


SUB Z c 


Substitute 


64 ".-,■ 


..,#./•• 




ComrnerciaJ at 


27 


ESC [ c 


Escape 


■< .-tB-t-.y-- 


"k '•' 




■ Uppercase A '■'•]:;' • 


28 


FS \ c 


File separator 


^BSppRl 


3 




Ujitwiiiase? B 


29 


GS ] c 


Group separator 


67 


c".' 




IBItf^^^fciidlid*sit 


30 


RS ac 


Record separator 


68 


D 




^^■^^^^■llfcsiiljiiliili 


31 


US - c 


Unit separator 


69 
70 

71 


E 
p 




Uppercase E 

^M^P^8j|||i|jl|||ii|i|i 


32 


SP v c 


ii^B^S^^^ftiilisSSiliii«i 


.. 




•'•'' 33 '.'•■ 


* * 


Exclamation poini 


72 


H 




f|(i^pl^^^S|!lfSiliil|ipl 


.■.•■:•'•■•;■*•■ ',* 


> ■ . b c 


Qi.'otatioi mark 


73 


IBS 




Uppercase l< 


35 


# > 


IfiSwI^pfciSfPtplsii 


74 


j 




Uppercase J 


-,' : .':\M-/-' 


$ d c 


Dollar sign* 


75 


K 




Uppercase K 


Sift^pit 


% e c 


Percent Sign 


76 


L 




^^Spi^^^^^^^^^^ 


3p ■ 


& i c 


Ampersand 


77 


M 




lip|^^S|^piipj|ig(|fif 


39 


9 C 


Apostrophe 


78 


N 




Uppercase W 


4fl 


( he 


Sitl^^^^Bi^^iiBilliis 


79 


O 




Uppercase O 



C-l 



Table C-l. ASCII Characters in Sequence (continued) 



DECIMAL 

VALUE 


CQNtTHOU 
GRAPHIC 


; COMMENTS 


DECIMAL 
VALUE 


CONTROL/ 
GRAPHIC 


COMMENTS 


StHRM 

V L : .-': 1B3- i ? 
; • :: }'" ' 84^'-' 

' ' m -i 

HmMH 
■■■HI 

HHM 

HflRH 


■ Q'\- 1 : - /•■'■'• 

■PWMI 

^Pj|™||J 

HHIN 

uHifll 


'.ijpperjbise'.Q'v: •' 
'-UppefjEasc-Ji'-;.':'';': i ■;• ."■-•' 
yp^ercascS 

UppercaMiVfiL '." 'J_ V;.":/ : ! ; 

■ Uppercase W"' ; '- : -^'"''TvK- ! J : 'i- 

Uppercas^'^i JLV? '"* ;r'-;^T ? 

• Upp9f«a^s-|!! - ',.'■•>'* %>•:>' 
Opening bracket 
Reverse &ant^ ^j^^f^-'u 
Closing brado^j?!' ; 7;- : ?0M;^ 
Circumf tetvvjf •';* :' ; ^~f " : - >^i: 

.Underscore . ' 'Jl vi! vi \ ■■ 


104 
105 
106 
107 
108 
109 
110 
111 


h 
i 

j 

k 

I 

m 

n 

o 


Lowercase h 
Lowercase i 
Lowercase j 
Lowercase k 
Lowercase I 
Lowercase m 
Lowercase n 
Lowercase o 


112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 


P 

q 

r 
s 
t 
u 

V 

w 

X 

y 

z 

{ 

I 

} 

DEL 


Lowercase p 
Lowercase q 
Lowercase r 
Lowercase s 
Lowercase t 
Lowercase u 
Lowercase v 
Lowercase w 
Lowercase x 
Lowercase y 
Lowercase z 
Left brace 
Vertical line 
Right brace 
Tilde 
Delete 


96 

97 

98 

99 

100 

101 

102 

103 


a 
b 
c 
d 

e 

f 

g 


Grave accent 
Lowercase a 
Lowercase b 
Lowercase c 
Lowercase d 
Lowercase e 
Lowercase f 
Lowercase g 
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CONVERSION TO KSAM FILES 



APPENDIX 



D 



In order to convert from your existing files to KSAM files, you may want to take advantage of 
utility programs provided with KSAM/3000. If your files are serially accessible, you can use the 
KSAMUTIL command BUILD to create a KSAM file and then copy your files to the new file 
with FCOPY. Another method only converts HP INDEX files. INDEX is the new name for RSAM 
(or R'ISAM) files. This method uses the program RTOKSAM. Finally, if neither of these methods is 
useful, you can write your own special purpose conversion program. 

USING KSAMUTIL AND FCOPY 

This conversion method can be used for any file that is serially accessible. First you create a 
KSAM/3000 file using the BUILD command of KSAMUTIL. At this time you can define your 
file with any legitimate specification of the BUILD command. Once the file is built (created), 
you can run FCOPY to copy your existing file to the newly created file. No special FCOPY 
commands are needed. You simply specify your existing file as the FROM= file and the newly 
created KSAM file as the TO= file. All connections between the data file and the key file are 
made automatically. (Refer to section II of this manual for a discussion of both the KSAMUTIL 
BUILD command and FCOPY as applied to KSAM/3000 files.) 



USING RTOKSAM 



The RTOKSAM program will create a KSAM/3000 file from an existing INDEX file. The KSAM 
file will have the same key structure as the INDEX file. Any number of INDEX files can be con- 
verted to KSAM/3000 files in one RTOKSAM run provided that you have sufficient disc space 
within your group and account for all the files. 

Program RTOKSAM is run as follows: 

: RUN RTOKSAM .PUB.SYS. 

HP32208.A.0.00 INDEX TO KSAM CONVERTER 

ENTER INDEX KEY, KSAM DATA, AND KSAM KEY FILE NAMES 

> indexkey ,ksamdata,ksamkey 

The names of the INDEX key file, the KSAM data file, and the KSAM key file must be entered in 
that order. Only the INDEX key file already exists; a new KSAM/3000 file wll be created with the 
specified names. 

After converting the INDEX file to the KSAM file, the program continues to prompt you for 
additional file names for conversion. When you wish to stop processing, simply press the 
carriage return key in response to the greater than (>) prompt. Or, if you are in a job, enter 
an :EOD record. 
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Record numbering in INDEX files always starts with record number 1. The KSAM file created 
by the RTOKSAM conversion program will also have record number starting with 1. Note that 
this is not the standard KSAM file default. Key blocking, on the other hand, does follow the 
KSAM file default. That is, the number of keys per block is determined by KSAM so that each 
key block has 1024 (IK) words. 

If errors occur during execution of RTOKSAM, the following error messages may be displayed: 

INPUT/OUTPUT ERROR ON $STDIN/$STDLIST 

COMMAND TOO LONG 

DUPLICATED FILE NAME 

INSUFFICIENT PARAMETERS 

INDEX OPEN ERROR (detail line follows message) 

INDEX FREADLABEL ERROR (detail line follows message) 

UNABLE TO BUILD KSAM FILE (detail line follows message) 

KSAM FILE WRITE ERROR (detail line follows message) 

INDEX FILE READ ERROR (detail line follows message) 



The detail line that follows certain of the RTOKSAM messages explains in more detail the 
input/output error that occurred. 

The normal MPE security provisions for files apply when the INDEX file is specified in this 
program. The KSAM file that is created must be within the same log on group. 



NOTE 

It is good practice to make a back-up copy of the INDEX 
file on off-line storage such as magnetic tape before running 
RTOKSAM to copy the file to a KSAM file. This allows 
you to purge the INDEX file once it is copied. 
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RECOVERY FROM SYSTEM FAILURE 



APPENDIX 



OVERVIEW 



If the system fails when a KSAM file is open for any type of access except read-only, the file cannot 
be reopened until it has been recovered. In such a circumstance, any attempt to reopen the file 
causes the following message to be issued: 

#192 - SYSTEM FAILURE OCCURRED WHILE THE KSAM FILE WAS OPENED 

The file is easily recovered in most cases by running KSAMUTIL.PUB.SYS and then requesting 
KEYINFO. This command resets any incorrect end-of-file marks and deletes any key values that 
point to non-existent data records. If key values are missing or are out of sequence, the keys cannot 
be recovered by KEYINFO and, in this case, the file must be reloaded. (You can refer to section II 
for a discussion of KEYINFO; also an example of file recovery and reloading is provided later in 
this appendix.) If you want to examine the file statistics, you can run the VERIFY command of 
KSAMUTIL using the NOCHECK option. (If KEYINFO does not complete execution successfully, 
then the KSAM file must be reloaded.) 

For most purposes, this is all you need to know in order to recover a file when a system failure 
prevents you from opening it. This appendix provides internal details that explain why recovery is 
necessary and what KEYINFO does in order to recover. It is intended primarily for the sophisticat- 
ed programming staff. 



END-OF-FILE ON KSAM FILES 

The first step in understanding what KEYINFO does and why it is needed, is to understand how 
KSAM end-of-files are set and maintained. Each of the two files that comprise a KSAM file (the 
data file and the key file) has two end-of-file marks: an MPE end-of-file and a KSAM internal 
end-of-file. Thus, there are four end-of-files to consider. The main characteristics of each of these 
end-of-files are shown below: 

DATA FILE 

MPE End-Of-File: 

Number of records in fixed-length record file (or number of blocks in variable-length 
record file). 

Stored in system file label of data file. 

Recorded on disc when file is closed (or when £;n SPL procedure calls FCONTROL with 
control code 6) or when a new extent is allocated. 

Used by FCOPY with NOKSAM option (KSAM file is treated as an MPE file). 
Displayed by LISTF,2: 



:LISTF DATAFIL,2 




ACCOUNT= 
FILENAME 


MORRIS 


GROUP= 




SIZE TYP 


DATAFIL 


KSAM 


38B FA 



JOAN 
LOGICAL RECORD-- 



EOF 



SPACE 

LIMIT R/B SECTORS #X MX 



20 1 23 

■MPE end-of-file for data file 



8 8 
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KSAM End-of-File: 

Address of next available logical record in the data file. 
Stored in control block of key file. 

Recorded on disc when file is unlocked or closed (or when an SPL procedure calls FCONTROL 
with control code 2 or 6). 

Used by FCOPY when file is opened as a KSAM file (KEY=option) 

Displayed by VERIFY command (option 1) of KSAMUTIL: 
:RUN KSAMUTIL.PUB.SYS 

HP32208A.2.3 MON, APR 23, 1979, 1:11 PM KSAMUTIL VERSION: A . 2 . 

>VERIFY DATAFIL 

WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?1 

DATAFIL. JOAN. MORRIS CREATORsJOAN 

FOPTIONS(004005)=KSAM, :FILE, NOCCTL, F, FILENAME, ASCII, PERM 
AOPTIONS(000400)=DEFAULT, NOBUF, DEFAULT, NO FLOCK, NO MR, IN 

recsize:sub:typ:ldnum : drt:un.: code:logical ptr: end of file:file limit 
-38: 3: o: 3: 5: 0: 0: o: Ah; 20 

LOG. COUNT:PHYS. C0UNT:BLK SZ:EXT SZ:NR EXT: LABELS :LDNj^ DISCADDR : 

1: is "38: 3: 8: 1^/3:00000010135: 

KSAM end-of-file for data file 

Since this is a file that closed successfully, the two end-of-files coincide. 

KEY FILE 

MPE End-of-File: 

• File limit — Number of records (sectors) allocated to file at time of creation 

• Stored in system file label. 

• Displayed by LISTF.2: 

:LISTF KEYFIL,2 

ACCOUNT= MORRIS GROUP= JOAN 

FILENAME CODE LOGICAL RECORD — - SPACE 

SJZE TYP EOF LIMIT R/B SECTORS *X MX 



KEYFIL 



KSAMK 128W FB <Q 50 1 30 5 8 



\ 



MPE end-of-file on key file 
(set to file limit) 
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KSAM End-of-File 

Address of 1st record in next available key block. 

Stored in Control Block of key file. 

Recorded on disc when file is unlocked or closed (or when SPL procedure calls FCONTROL 
with control codes 2 or 6). 

Used by FCOPY and KSAM procedures. 

Displayed by VERIFY command, option 3, of KSAMUTIL: 



WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAH CONTROL, 4=ALL)?3 



DATA FILE = DATAFIL 




VERSI0N= A. 2 


.1 












KEY CREATED=292/ 


'78 


10:19: 7,4 


KEY 


ACCESS= 


113/ *79 13:11: 


45.8 




KEY CHANGED= 


93/ 


'79 


14:1 


18: 7.6 


COUNT 


START: 


:292/'78 10:19: 


53.6 




DATA RECS = 






20 


DATA BL0CKS= 






19 


END BLK WDS= 




19 


DATA BLK SZ= 






19 


DATA REC SZ= 






38 


ACCESSORS= 







FOPEN 






2 


FREAD 









FCLOSE 




2 


FREADDIR 









FREADC 









FREADBYKEY 







FREMOVE 









FSPACE 






57 


FFINDBYKEY 







FGETINFO 






3 


FGETKEYINFO 






1 


FREADLA8EL 







FWRITELABEL 









FCHECK 









FFINDN 




3 


FWRITE 






20 


FUPDATE 









FPOINT 







FLOCK 









FUNLOCK 









FCONTROL 







FSETMODE 























KEYBLK READ 






7 


KEYBLK WROTE 









KEYBLK SPLIT 







KEY FILE EOF 








FREE KEY HD 









SYSTEM FAILURE 







MIN PRIME 






/if 


MAX PRIME 






5 


RESET DATE 


3/ 


'79 


DATA FIXED 






rRUE 


DATA B/F 






1 


TOTAL KEYS 




3 


FIRST PECNUM 









MIN RECSIZE 






38 









KSAM internal end-of-file on key file 



Since the MPE end-of-file is set to the file limit and the KSAM internal end-of-file to the next 
available key block, these values never coincide until the key file is full. 
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END-OF-FILE AND THE EXTRA DATA SEGMENT 

As described in appendix B, each open KSAM file uses an extra data segment (XDS) to hold the 
control information for that particular open file. The extra data segment also contains a data 
block buffer into which records are read from the file and from which records are written. 
Finally, the extra data segment keeps key block buffers to hold key entries affected by the 
data records being accessed. The control block in each extra data segment also maintains the 
most up-to-date KSAM end-of-file markers for each open file. 

Whenever a KSAM file is opened, the KSAM end-of-files for the data and key files are moved 
(with all other information from the key file control block) to the control block of the extra 
data segment for that file. When the file is closed or unlocked, the control block is written back 
to disc. (Refer to figure E-l for a diagram illustrating the end-of-file markers and their relation 
to an extra data segment.) 



disc 

I 



Data File 



Key File 



XDS 
for Open file 



last 

data 

block 



i> 



File Label 
(MPE EOF) 



Control Block 
(key file EOF 
data file EOF) 



Open/Lock 



Close/Unlock 



Control Block 
(key file EOF 
data file EOF) 



<f 



<> 



3-20 key 
block buffers 



data block 
buffer 



key block 
buffers 



MPE EOF 
(next available 
record or block) 



MPE EOF 
(file limit) 

KSAM EOF 
(next available 
logical record) 



KSAM EOF 
(next available 
key block) 



Figure E-l. KSAM File and an Extra Data Segment 
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NORMAL OPERATION - FILE IS CLOSED 

During normal operation, if a new record is written to the file by any user, the record is written 
in the data block buffer of the extra data segment and the key entry for the record is inserted into 
the key block buffer where it belongs. (Refer to appendix B for a discussion of how new key entries 
are added.) The appropriate key block buffer is brought into the extra data segment automatically. 
Then, whenever the data block or key block buffers are full or new blocks must be read into the 
extra data segment, the key and data blocks are written back to disc. But the control block from the 
extra data segment is not written to disc until the file is closed (or is unlocked, or FCONTROL with 
code 2 or 6 is called). 

Before considering what happens in case of a system failure, let's look at the normal steps taken 
when the file is closed: 

(T) Key block buffers are written to the key file 

(2) Data block buffer is written to the data file (and, if a new extent is allocated, the MPE 
end-of-file is written to the data file system label). 

(3) Control block with the KSAM end-of-file marks is written to the key file. 

(4) MPE end-of-file mark is written to the data file system label. 

When a file is unlocked, the first three steps shown above are taken (except the MPE end of file 
is not written). FCONTROL with control code 6 performs all four steps, and control code 2 per- 
forms the first three steps. 

SYSTEM FAILURE - FILE IS OPEN 

If the system fails when a KSAM file is open, the extent of the damage to the file depends on when 
the failure occurred and whether the file was being modified. If all users opened the file for read- 
only, then the file is undamaged and can be reopened. If a user had just unlocked the file and no 
other user has modified it, the MPE end-of-file may need to be reset but otherwise, the file is un- 
damaged. But if the file was being modified, then the extent of the damage depends on whether 
any of the steps listed above had been completed and, if so, which ones. 

In the simplest case, all the steps except step 4 have been performed. This means that the KSAM 
end-of-file is up-to-date, but the MPE end-of-file is still at its previous position. In the most com- 
plex case, caused by records being deleted, data records remain in the data file for which there are 
no corresponding key entries, (error number 175). 
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SITUATIONS IN WHICH RECOVERY 
IS REQUIRED 

Whenever the file cannot be reopened (error #192 is issued), you must run KEYINFO to recover 
the file. The following four cases are typical of the reasons for file damage. In each case, the sug- 
gested action is discussed. 

1. Records were being added to the data file when the system failed. The KSAM end-of-file for 
the data and key files are current, but the MPE end-of-file precedes the KSAM end-of-file 
(steps 1-3 completed). 

Solution: Run KEYINFO to reset the MPE end-of-file. You can then run the KSAMUTIL 
command, VERIFY, to determine where the current KSAM end-of-file for the data file is posi- 
tioned, and then run the MPE command :LISTF 2 to compare the MPE end-of-file. If you run 
VERIFY before running KEYINFO, use the NOCHECK option so the file can be opened. 

2. Records being added to the KSAM file when the system failed were not written to the data 
file, but some key entries for the new records had been written to the key file (key blocks 
written to key file because buffer space in XDS was needed). This means that the key file 
contains key values pointing to records not in the data file. 

Solution: Run KEYINFO to delete the key values that point to records that were not writ- 
ten to the data file. 

3. Records being added to the KSAM file when the system failed caused a key block split. As a 
result, the key blocks are written, but the new internal KSAM end-of-file for the key file has 
not been transferred to disc. This places certain key values past the old KSAM key file 
end-of-file. 

Solution: Run KEYINFO to reset the key file end-of-file to the correct location following 
the existing key values. It still may have to delete any key values pointing to records past the 
data file end-of-file. 

4. Records were being deleted when the system failed. Some key block buffers have been written 
to disc, but the data block buffer has not. Since some key entries were deleted from the file on 
disc, but the deleted records remain, key values appear to be missing. 

Solution: You must run KEYINFO to reset the crash flag so the file can be reopened. When 
key values are missing, KEYINFO cannot fully recover from the file damage and issues the 
following message: 

WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING THE 
KSAM FILE HAS TO BE RELOADED 

To reload the KSAM file, use FCOPY to copy the file to a new KSAM file. As it copies the 
data records, it writes new key entries for each data record. Only in this way can missing key 
values be recovered. (Refer to the discussion of Reloading a KSAM File later in this section.) 

If you want to determine how many key values are missing and the file has more than one key, you 
can compare the number of values in each B-Tree as listed by KEYINFO. These values should be 
identical. When there is only one key in the file, you can use FCOPY to determine the number of 
non-deleted records in the batch file. The number of key values for any key in the file should ex- 
actly match the number of valid data records. The FCOPY command to determine this value is: 

> FROM=filename;TO=$NULL;KE Y=0 



E-6 



If your file is very large, using this FCOPY command can be time consuming and you may prefer 
to reload the file without checking the number of missing keys. 

EXAMPLE OF FILE RECOVERY 

Suppose you try to open file TEST and receive error message #192: 

SYSTEM FAILURE OCCURRED WHILE KSAM FILE WAS OPENED 

In order to have the most information about the file, first run KSAMUTIL and request VERIFY 
to list all the file information. 



KSAMUTIL VERSIONS*. 3.0 
WHICH (1«FILf INFO. 2=K5AM PARAmETEKS. 3=KS>AM CONTROL' 4=ALL)?4 



HP32208Y.2.4 THU, MAS R, 1979, 1?!53 PM 
>V TEST 



SYSTEM FAILURE OCCUHHfEO wmILE ThE KSAM Flit WAS OPENED U16fl>-»- 



KSAMUTIL 
error message 



Just like any other program, the VERIFY command cannot open the damaged file. So try again 
using the NOCHECK option that allows such a file to be opened for read-only: 



>V TESTJNOCMECK-«- 



Option 
1 



Option . 
2 



-forces open 



WHICH <l«FILf INFO. 2.KSAM PARAMETERS, 3=KS>AM CONTROL' 4=ALL)?4 

TEST. KSAM. UTILITY CRE«TOR*ONG 

FOPTIONS(00*00b>»KSAM, JFTLE, MoCCTL, F, FILENAME, ASCII, PERM 
AOPTIONS(00<H00l»DEFAuLT, NOBUF, DEFAULT, NO FLOCK, NO MR, IN 
RECSIZElSU8ITvP«LONUM|0RTtUN.« COOEiLOGIcAL PTR8 END OF FTLEtFILE LI*! 1 
-801 3' V 3' *" 0» 01 01 gMl— — 1^23 

LOG. COuNUPHYs. COUtgTtRLK SZ t FXT SZJNR fxTi LABELSsLONi DISCADDRJ 
10« l« -BOOl 52! Hi 01 l!0(100012f 173« 



KEY FILE»TE=TK 



KEY FILF DEVTCE«4 



size= 



FLAGWORD(000000>«RANOOI» PRIMARY, FIRST KECOKD=0, PERMANENT 
KEY TY LFNGTh LOC. KFY BF LEVEL 

IB 8 73 M 126 2 

2 B 6 20 Y 1*4 2 



|2T3 KEYS' 



KSAM 

■ data file 
end-of-file 

-file limit 



Option 
3 



DATA FILE ■ TEST 

KEY CREATED- 61 /» 

KEY CHANGED 

0ATA RECS * 

DATA BLK SZ* 

FOPEN 

FREADDIR 

FREM0VE 

FGETINF0 

FWRITELAREL 

FWRITE 

FLOCK 

FSETMOOE 

KEYBLK READ 

KEY FILE EOF 

MlN PRIMF 

DATA FIXED 

FIRST RECNUM 



VFRSION* Z.2.4 
79 17I3M29.8 KEY AcCtsS= 

= 67/»79 12:S?:41.7 COUNT START' 



# of non-read-only opens 
when system failed 



990 DATA BLOCKS' 

400 DATA REC S* s 

3 FREAD 

FPEADC 

FSPACE 

3 FGETKEYlNFO 

FCHECK 

1000 FUPOATF 

FMNLOCK 

*FYRLK WROTE 
FREE KFy HD 
MAX PRIME 
TRUE OATA B/F 

MIN REcSlZE 




99 
80 



2 




89 



999 

10 

80 



67/»79 12l54J17.fi 
67/«79 1215U20.7 

END BLK WD5= 

ACCESSOHS= 

f CLOSE 

FREADBYKEY 

FFINDBYKEY 

FREADl ABEL 

FF'INDN 

FPOINT 

F CONTROL 

KEYBLK SPLIT 
SYSTEM FAILURE 
RESET DATE 
TOTAL KEYS 




23 



"-^ incremented 
? S after recovery 



KSAM internal end-of-file 
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The next step is to run LISTF,2 to see where the MPE end-of-file is positioned. Note that you can 
request the MPE command without exiting from KSAMUTIL. 



>:LISTF TEi>T,2 
ACCOUNT^ UTtLITY 



G«ntiP= KSAM 



FILENAME CODE 
TEST KbAM 



•— -lOrtCAL RECORn--— — SPACE 

SIZ TYP tOF LIMIT R/R SECTORS #X MX 



60h FA 



m 



1 0ii3 In 416 ft 8 

MPE end-of-file on data file 



LISTF shows the MPE end-of-file after the first 900 records, whereas option 1 of VERIFY showed 
the KSAM end-of-file after 990 data records. This is a discrepancy of 90 records. These records 
actually exist. You only have to run KEYINFO to reset the MPE end-of-file. When you run 
KEYINFO, however, you may find that there are other problems. 

>KI TEST 
RECOVERY BEGINS 

DATA FILE EOF DAMAGED 

OATA FILE MRE EOF H< S BFFM RESpT TO KSAM FUr*— 



— MPE end-of-file recovered 

After resetting the MPE end-of-file for the data file, KEYINFO continues. It next displays informa- 
tion on the two keys in the file TESTK. 



INFO FOR KEY 



# OF LEVELS OF 8-TREE 
<# OF KEY BLOCKS 

# OF SECTORS PER KEY *L0CK 

* OF KEYS IN ROOT KEY BLOCK 
» OF KEYS IN B-TREE 

* OF KEY 8L0CK UTILIZATION 
THE LARGEST KEY BLOCK ADDRESS 



......... INFO FOR KEY l 

# OF LEVELS OF B-TREE 

# OF KEY BLOCKS 

# OF SECTORS PER KEY *L0CK 

# OF KEYS IN ROOT KEY BLOCK 

# OF KEYS IN B-TREE 

# OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK ADDRESS 

WARNING: THERE ARE SOmE RFC0RD(S> WITH KEY VALUE (S) MISSING 
OR KEY VALUE (S) POInTinG TO DATA RECORO BEYOND EOF 



2 




16 




S]^__ 




u 


— -^_ KSAM end-of-file should 


11000k 


^^-"■"^ be at least 21 8 


52. r\^^ 




m^\^ 






>v # of key entries in two 


2 


n keys do not match 


11 

8 .. 

9 ^^""^ 


^^"^ each other; do not match 


# of data records 


|997K"^ 




68.6 




202 





KEY FILE EOF (INTERNAL) DAMAGED 

KEY FILE UNTERNADEOF H*S BFEn RESET — 



End-of-file moved forward 
so all key blocks are included 



Looking at the key information displayed for the two keys, the first thing to check is where the 
actual end of file should be. The largest key block address for key 1 is 210 and each block requires 
8 records, therefore the key file end-of-file should be at least 218. If you look back to option 3 of 
the VERIFY display, it is listed as 210. Since this is not the real end-of-file, KEYINFO resets the 
KSAM internal end-of-file to the actual end of file (see VERIFY display, below). 
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Next, check the total number of key values for each key. The first thing to notice is that they do 
not match each other. The number of key values for each key should always be the same, and each 
should equal the number of records in the data file. But, if you look at option 1 of the VERIFY 
display, the number of records in the data file is 990, less than the number of key values for either 
key. (Note that if the file contains records marked for deletion, you can run FCOPY to determine 
the number of active records). 

In response to this discrepancy, KEYINFO deletes 10 key values from each key. The values delet- 
ed are those that have no matching data record. This completes the KEYINFO functions. Now that 
it has deleted 10 key values from the key entries for key 2, only 987 are left (997 minus 10). This 
is three fewer than the number of key values in key 1 (990 = 1000 -10). For this reason, KEYINFO 
must issue the warning that the file needs to be reloaded: 



... ... ... Kfcy SEQUENCE 1 

# OF INVALID KEY VALUES DELETED 

— — Kty SEQUENCE 2 

* OF INVALID KEY VALUES DELETED 




1 values deleted that 

have no matching data record. 



RECOVERY ENDS 

WARNING! THERE ARE SOmE RECORD (?) WITH KEY VALUE (S) MISSING 
THE KSAM FILE HAS TO BE RELOADED 



Before reloading the file, as described below, use LISTF, 2 to check the current MPE end-of-file 
(after recovery); run VERIFY to check the current KSAM end-of-file positions; and run 
KEYINFO again to see the number of key values left in each key following the previous 
KEYINFO recovery. 
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>ILISTF TEST, 2 
ACCOUNT" UTILITY 



GROUP* KSAM 



FILENAME CODE 

TEST KSAM 
>V TEST 



SIZ 



LOpiCAL RECORD-- SPACE 

TVP EOF LIMIT R/e SECTORS #X MX 



Ft 



l*90l _ 



1023 in 



416 



WHICH <1«FILE INFO. 2"KS»M PARAMETERS. 3«K!>AM CONTROL. 4=ALL>?4 



TEST. KSAM. UTilIT 
FOPTIONS(00*00S) 
AOPTIONS<000400> 
RECSIZElSUB»TYP> 
-801 3» ?' 
LOG. COUNT«PHY<; 
101 
KEY FILE»TE TK 
FLAGWORO(OOOoOO) 
KEY TY LENGTH 

1 B 8 

2 B 6 
DATA FILE - TEST 
KEY CREATED" 6J/ 
KEY CHANGED" 67/ 
DATA RECS = 
DATA BLK SZ* 
FOPEN 
FREADOIR 
FHEMOVE 
F6ETINF0 
FWHITELABEL 
FWRITE 

FLOCK 
FSETMOOE 
KEYBLK READ 
KEY FILE EOF 
WIN PRIMF 
DATA FIXED 
FIRST RECNUM 



CRE»TOR=ONG 
"KSAM, 1FILE, NOCC'L, F. FlLENAMt, ASCII. PERM 
"DEFAULT, NOBUF, DEFAULT. NO FLOCK, NO MR, i N 
LDNl)MjO»TlUN.« CODEILOGICAL PTHI END OF FILE ZFILF LIMI I 

3« si oi "i oi lo9n|: lu?3 

COUNTltJlK SZ,EXT SZ:NR FXTj LABELSlLDN: DISCAODf 

1: -800' 52! ds 01 J:OoO00I26173l 
KEY FILF DEVICE«4 SIZE" 274 KEYS" 

■RANDOM PRIMARY. FIHST RECOHD"U. PERMANENT 
LOC. C) KEY BF LEVEL 
73 N 126 2 
20 Y 144 2 

VFRSION" Z.2.4 
3*129.8 KEY ACCtsS" 67/«79 12I56S19.6 
54152.3 COUNT SlART" 67/«79 12t51«20.7 




DATA BLOCKS" 

OATA REC SZ» 

FREAD 

FREADC 

FSPACE 

F<5ETKEYlNFO 

FCHECK 

FUPOATF 

FUNLOCk 

KFYRI.K WROTE 
FREE KFY HU 
MAX PRtME 
flATA B/c 
TN RECSlZE 



p9] END ai K tfp<;« 



80 ACCESSOHS" 

FCLOSE 

FHEADBYKEY 

*024 FFINDRYKEY 

4 FREADLA«£L 

FFINDm 

FPOINT 

FCONTROL 



40Q 



96 KEYBLK SPLIT 23 

SYSTFM FAILURE H 

989 RtSET DATE 67/«79 

10 TOTAL KEYS ? 
80 



New MPE EOF 
matches 



KSAM EOF 



For variable-length 
files, MPE EOF must 
equal the number of 
data blocks + 1 



system failure 
' count 
■ recovery date 



• MICH (laFILE INFO, 2aKSAM PARAMETERS, 3»KSAM CONTROL. 4"4LD? 
>KI 



Follows last 
possible key 
entry 



INFO FOR KEY 



» OF LEVFLS OF q-TREE 

• OF KEY BLOCKS 

• OF SECTORS PER KEY .(LOCK 
» OF KEYS IN RooT KEY BLOCK 
» OF KEYS IN B-TREE 

• OF KEY BLOCK UTILIZATION 
THE LARGEST KEY BLOCK AOORESS 



INFO FOR KEY 



# OF LEVELS OF B-TREE 
» OF KEY BLOCKS 

# OF SECTORS PER KEY hLOck 

# OF KEYS I« ROOT KEY BLOCK 

# OF KEYS IN B-TREE 

# OF KEY BLOCK UTILIZATION 

THE LARGEST KEY BLOCK AOORESS 

HARNINGJ THEpE ARE SO*E RFCORDfO WITH KEY YALUt(S) MISSING 
OH KEY VALUE(S> POINTING TO DATA KtCORu BEYOND EOF 




(8+210) 



after recovery, # of key values 
do not match 



The name of the user who runs KEYINFO to recover the file for the RESET DATE shown by 
VERIFY is stored in the key file control block, along with his account, group, and home group 
(refer to figure B-5). 
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RELOADING A KSAM FILE 



You use FCOPY to reload a KSAM file when KEYINFO cannot recover the file. In general, you 
should use the KEY=0 option of FCOPY (see section II for a complete description of the FCOPY 
options for KSAM files). KEY=0 copies the file in chronological sequence so that the new file will 
be an exact copy of the original file, except that records marked for deletion are physically deleted 
from the file. 

For example, to reload the file TEST to a new KSAM file, NEWTEST: 

: RUN FCOPY.PUB.SYS 

> FROM=TEST;TO=(NEWTEST,NEWKEY) ;KEY=0;NEW 

After the file is successfully reloaded, you should purge the old file TEST and rename the file 
NEWTEST. To do this, run KSAMUTIL and use the PURGE and RENAME commands as follows; 

: RUN KSAMUTIL.PUB.SYS 

HP32208V2.4 THU, MAR 8, 1979, 1:05 PM KSAMUTIL VERSION:A.3.0 

> PURGE TEST 

TEST,TESTKEY PURGED 

> RENAME NEWTEST,TEST 

> RENAME NEWKEY,TESTKEY 

Now you can run any existing programs that referenced the old file TEST. 

The only time you might not want to use the KEY= option to reload a damaged file is if the key 
file has been accidentally purged. In this case, and if the file has fixed-length records, you can use 
the NOKSAM option. This option needs only the original data file. As it copies the data file in 
chronological order to a new KSAM file, it creates a key file with key entries for the data records. 
The NOKSAM option does not, however, allow you to copy a data file with variable-length records. 

For example, to reload a KSAM file for which you have only a data file with fixed-length records, 
you can use the following FCOPY command: 

> FROM=DATAFIL;TO=(NEWFIL,NEWKEY);NOKSAM;NOUSERLABELS ; 



SUBSET=#%377,%377#, ,EXCLUDE 

s ' 

to exclude records marked you must not copy 

for deletion by -1 in user labels to a 

first two characters KSAM file 

This command copies only the non-deleted records; it creates a new KSAM file with only valid 
records and a key file that has key entries for each data record. 

After a system crash in which the key file is lost, it is possible that the MPE end-of-file follows the 
KSAM end-of-file because it was written to disc just before the crash. If this is the case and you use 
the NOKSAM option you should also use a SUBSET option to copy only the records up to the 
KSAM end-of-file, not the undefined area between the KSAM and MPE end-of-files. 
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EXPAND KEY BLOCK BUFFER AREA 

Depending on the length of the existing file, the reloading procedure can take a long time. One way 
to shorten this time is to increase the number of key block buffers in the extra data segment for the 
file. Since reloading is a write-only operation, the more buffers that can be allocated to key blocks, 
the less swapping is needed between the extra data segment and disc as new key entries are added. 

In order to increase the number of key block buffers, enter the following commands: 

: RUN FCOPY.PUB.SYS 

> FROM=TEST;TO=(NEW,NEWK);SUBSET=1.0 ^ create new file with records 

>: FILE F=NEW;DEV= , ,20 - increase number of key block buffers 

> FROM=TEST;TO*F;KEY=0 «■ copy data in chronological order 



n 



remember to back reference file 
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Abbreviations.KSAMUTIL commands 2-3 
Access, 

approximate match 1-4 

duplicate keys 1-3 

generic key 1-4 

multiple key 1-3 
Access mode, 

BASIC 6-16,-17 

COBOL 3-4 

SPL 4-41,-46 
Access options,FOPEN (see aoptions) 
Accessing KSAM files 1-2 
Add keys to B-tree B-2 
Alternate key positioning, 

BASIC 6-33 

COBOL 3-38 

SPL 4-22,-26,-63 
Analysis of files capability 1-7 
aoptions parameter,FOPEN 4-41,-46 
Approximate key access 

BASIC 6-32 

SPL 4-22,-23 
Approximate match capability 1-4 
ASCII character set C-l 
ASCII records, 

BUILD 2-10 

FOPEN 4-45 



B 



B command (see BUILD) 
B-tree 

number of levels 2-38 

structure B-2 
Backspace file.SPL 4-88 
Backup files 

to serial disc 2-55 

to tape 2-55 
BASIC 

error messages A-6 

features 1-11 

interface 6-1 

procedures,summary 6-3 
Batch execution.KSAMUTIL 2-43 
Binary records, 

BUILD 2-10 

FOPEN 4-45 
BKCLOSE 

call,BASIC 6-8 

example 6-9 
BKDELETE 

call,BASIC 6-10 

example 6-11 
BKERROR call.BASIC 6-12 



BKLOCK 

call,BASIC 6-14 

example 6-15 
BKOPEN 

call,BASIC 6-16 

example 6-21 
BKREAD 

call,BASIC 6-22 

example 6-25 
BKREADBYKEY 

call,BASIC 6-26 

example 6-28 
BKREWRITE 

call,BASIC 6-29 

example 6-31 
BKSTART 

call.BASIC 6-32 

examples 6-24,-35 
BKUNLOCK 

call,BASIC 6-36 

example 6-37 
BKVERSION call,BASIC 6-38 
BKWRITE 

call.BASIC 6-39 

example 6-42 
Block size, 

BUILD 2-9 

FOPEN 4-43 
Blocking factor, 

BUILD 2-9 
FOPEN 4-43 
Buffers,number of,FOPEN 4-43 
BUILD command, 
KSAMUTIL 2-8 

use of 2-16 
BYTE key type 2-15 



Call KSAM intrinsics, 

FORTRAN 5-2 

SPL 4-3 
Call KSAM procedures, 

BASIC 6-2 

COBOL 3-2 

FORTRAN 5-3 
CALL statement, 

BASIC 6-2 

COBOL 3-2 

FORTRAN 5-2 
Chronological read, 

FORTRAN 5-13 

SPL 4-68 
Chronological record pointer.SPL 4-5 
CKCLOSE 

call,COBOL 3-12 

examples 3-14,-47 
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CKDELETE 

call,COBOL 3-13 

examples 3-14,-52 
CKLOCK 

call.COBOL 3-18 

example 3-19 
CKOPEN 

call,COBOL 3-20 

examples 3-23,-47 
CKOPENSHIR call,COBOL 3-25 
CKREAD 

call,COBOL 3-26 

examples 3-27,-48 
CKREADBYKEY 

calI,COBOL 3-29 

examples 3-30,-51 
CKREWRITE 

call,COBOL 3-32 

examples 3-34,-51 
CKSTART 

call.COBOL 3-36 

examples 3-37,-48 
CKUNLOCK call,COBOL 3-40 
CKWRITE 

call,COBOL 3-42 

examples 3-43,-46 
Clear £ile,ERASE 2-19 
Close file, 

BASIC 6-8 

COBOL 3-12 

SPL 4-12 
COBOL 

error messages A- 5 

examples 3-46 

features 1-9 

interface 3-1 

procedures from FORTRAN 5-3 

procedures,summary 3-2 
Collating sequence C-l 
Command abbreviations,KSAMUTIL 2-3 
Complete input/output,SPL 4-17 
Control block,key file B-5 
Conversion to KSAM files D-l 
Copy KSAM file,FCOPY 2-45 
Crash recovery 2-27,-40;E-l 
Create capabilities 1-6 
Create file, 

BUILD command 2-8 

BUILD examples 2-16 

FCOPY 2-49 

FORTRAN 5-4,-7 

SPL 4-50 



D 

Data buffers,FOPEN 4-43 
Data file name, 

BUILD 2-8 

FOPEN 4-41 
Data file/key file relation B-9 
Data record format 1-5 



Delete file, 

PURGE 2-20 

SPL 4-15 
Delete keys from B-tree B-2 
Delete record, 

BASIC 6-10 

capability 1-7 

COBOL 3-13 

COBOL example 3-51 

SPL 4-80 
Device specification, 

BUILD 2-10 

FOPEN 4-41 
Display error message, 

BASIC 6-12 

COBOL 3-20 

SPL 4-20 
Display file.FCOPY 2-52 
Display file characteristics, VERIFY 2-24 
Display offline 2-3 
DOUBLE key type 2-15 
Dump key file 2-31 
Duplicate key, 

BUILD 2-13 

capability 1-3 

FOPEN 4-47,-49 

random insertion 2-13;4-49 
Dynamic access,COBOL 3-22 
Dynamic access code.COBOL 3-4 
Dynamic locking 

BASIC 6-14 

COBOL 3-18 

SPL 4-38 



E 



E command (see ERASE) 
End-of-file, 

data file E-l 

key file E-2 
EOF, 

data file 2-40;E-l 

key file 2-40;E-2,-3 

MPE 2-27,-40;E-l 
ERASE command 2-19 
Error checking 

BASIC 6-4 

COBOL 3-6 

SPL 4-7 
Error code translator,SPL 4-20 
Error messages A-l 
errorcode list 4-8;A-l 
Exclusive access, 

BASIC 6-17 

SPL 4-46 
EXIT command, 

FCOPY 2-45 

KSAMUTIL 2-4 
Extent allocation, 

BUILD 2-11 

FOPEN 4-44 
Extents,number of 2-ll;4-49 
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Extra data segment size B-18 
Extra data segments, 

definition B-17 

end-of-file marker E-4 

shared access B-21 



FCHECK call,SPL 4-7 

FCLOSE call.SPL 4-12 

FCONTROL call.SPL 4-17 

FCOPY 2-45 

FCOPY error messages A-14 

FCOPY, 

function summary 2-47 

to list files 2-52 

use with KSAM 2-48 

using KEY= 2-50 

using NOKSAM 2-51 

without KSAM options 2-48 
FERRMSG call, SPL 4-20 
FFINDBYKEY 

call,SPL 4-22 

example 4-25 
FFINDN call,SPL 4-26 
FGETINFO 

call,SPL 4-28 

example 4-33 
FGETKEYINFO call,SPL 4-35 
File access capability 1-2 
File analysis capability 1-7 
File capacity, 

BUILD 2-11 

FOPEN 4-43 
File characteristics, 

FGETINFO 4-28 

FOPEN (see foptions) 

VERIFY 2-24 
File code, 

BUILD 2-11 

FOPEN 4-44 
File error list 4-8;A-l 
File errors, FCHECK 4-7 
File equations 1-8 
File label,read in SPL 4-76 
File name, 

BUILD 2-8 

FOPEN 4-41 
File sequence 1-2 
File size, 

BUILD 2-11 

calculation of B-ll 

FOPEN 4-43 
File status request, 

SPL 4-28 

VERIFY 2-24 
File structure 1-1, B-l 

diagram of 1-5 

internal B-l 
File system error codes A-2 



File system intrinsics, 

FORTRAN 5-2 

SPL 4-1 
Filetable parameter,COBOL 3-4 
Find key 

BASIC 6-32 

COBOL 3-36 

SPL 4-22 
Fixed length records, 

BUILD 2-9 

FOPEN 4-45 
FLOCK call,SPL 4-38 
FOPEN 

call,SPL4-41 

example, create file 4-51 

example, open file 4-53 
FORTRAN features 1-11 
FORTRAN interface 5-1 
Forward space file,SPL 4-88 
FPOINT call,SPL 4-57 
FREAD 

call,SPL 4-59 

example 4-61 
FREADBYKEY 

call 4-63 

example 4-66 
FREADC 

call,SPL4-68 

example 4-70 
FREADDIR 

call,SPL4-72 

example 4-74 
FREADLABEL 

call,SPL 4-76 

example 4-77 
FREADSEEK call 4-78 
FRELATE call 4-79 
FREMOVE 

call 4-80 

example 4-83 
FRENAME call 4-85 
FROM command,FCOPY 2-46 
FSETMODE call,SPL 4-86 
FSPACE call,SPL 4-88 
FUNLOCK call,SPL 4-91 
FUPDATE 

call.SPL 4-92 

example 4-95 
FWRITE 

call,SPL 4-97 

example 4-99 
FWRITEDIR call.SPL 4-100 
FWRITELABEL call,SPL 4-101 

G 

Generic key access, 

BASIC 6-32 

COBOL 3-36 

SPL 4-22 
Generic key capability 1-4 
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H 

H command (see HELP) 

HELP command.KSAMUTIL 2-5 

HP32208 intrinsic,SPL 4-103 



I 



Input only, 

BASIC 6-16,-18 

COBOL 3-4,-21 

SPL 4-46,-53 
Input-output, 

BASIC 6-16,-18 

COBOL 3-4,-21 

SPL 4-46 
Input/output verification, SPL 4-86 
INTEGER key type 2-15 
Interna] structure,KSAM files B-l 
Intrinsic format,SPL 4-3 
Intrinsics,KSAM 4-1 
Invalid key, 

COBOL rewrite 3-33 

COBOL write 3-43 



K 



KD command (see KEYDUMP) 
Key block buffer size, during reload E-12 
Key block buffers, number of B-20 
Key block, 

calculation of size B-l 2 

size B-ll 

utilization, percent of 2-38 
Key blocking, 

BUILD 2-12 

FOPEN 4-47,-49 
Key blocks,number of 2-38 
Key description, 

BUILD 2-12 

FOPEN 4-47 
Key descriptor block,key file B-5 
Key device, 

BUILD 2-14 

FOPEN 4-47,-48 
Key entries, 

number of,BUILD 2-13 

number of,FOPEN 4-48 
Key entry block, key file B-8 
Key file characteristics, 

FGETKEYINFO 4-35 

KEYINFO 2-38 
Key file/data file relation B-9 
Key file definition, 

BUILD 2-11 

FOPEN 4-41,-47 
Key file formatted dump 2-31 
Key file information 

FGETKEYINFO 4-35 

KEYINFO 2-38 



Key file name, 
BUILD 2-11 
FOPEN 4-41 
Key file size, 
BUILD 2-13 

calculation of B-l 3 
FOPEN 4-47,-48 
Key file status request, 

FGETKEYINFO 4-35 

VERIFY 2-24 
Key file structure B-5 

diagrams B-6,-7 
Key location, 

BUILD 2-12 

FOPEN 4-47,-49 
Key sequence.verification 2-28 
Key size, 

BUILD 2-12 

FOPEN 4-47,-49 
Key type, 

BUILD 2-12 

FOPEN 4-47,-49 
Key types 2-15 

Key values,sequence check 2-28 
KEY= option,FCOPY 2-50 
KEYDUMP command,KSAMUTIL 2-31 
KEYINFO command,KSAMUTIL 2-37 
Keys, 

number in B-tree 2-38 

number in root block 2-38 
KEYSEQ eommand,KSAMUTIL 2-28 
KI command (see KEYINFO) 
KS command (see KEYSEQ) 
KSAM, 

BASIC interface 6-1 

COBOL interface 3-1 

file system intrinsics 4-1 

FORTRAN interface 5-1 

internal file structure B-l 

SPL interface 4-1 

summary of FCOPY options 2-47 

summary of features 1-3 

utilities 2-1 
ksamcontrol parameter,FGETKEYINFO 4-46 
ksamparam, 

format, FOPEN 4-47 

parameter, FOPEN 4-41 
KSAMUTIL 2-3 

commands, summary 2-2 

error messages A-8 



Labels, 

BUILD 2-14 
FOPEN 4-43 
read in SPL 4-76 
write in SPL 4-101 

Line printer display, 
FCOPY 2-52 
KSAMUTIL 2-3 
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Lock file, 

BASIC 6-14 

COBOL 3-18 

SPL 4-38 
Logical record pointer, 

BASIC 6-7 

COBOL 3-9 

SPL 4-5 
LONG key type 2-15 

M 

Modify record, 

BASIC 6-29 

COBOL 3-32 

COBOL examples 3-34,-51 

SPL 4-91 
Multiple key capability 1-3 

N 



Position by key value, 

BASIC 632 

COBOL 3-36 

SPL 4-23 
Position by key value and read, 

BASIC 6-26 

COBOL 3-29 

SPL 4-63 
Position file capability 1-7 
Position to first record,SPL 4-17,-26 
Position to lease-valued key, 

BASIC 6-34 

COBOL 3-37 

SPL 4-23 
Post buffer to disc,SPL 4-17 
Previous operation,COBOL 3-5 
PURGE command 2-20 
Purge file, 

FCLOSE 4-15 

PURGE command 2-20 



NEW option.FCOPY 2-47 
NOCHECK option.VERIFY 2-24,-27 
NOKSAM option, 

description, FCOPY 2-51 

syntax 2-47 
NUMERIC key, 

type 2-15 

signed digit 2-16 



O 



Offline display 2-3 

Open file after system failure, 

KEYINFO 2-40 

VERIFY 2-24,-27 
Open file for shared access,COBOL 3-25 
Open file, 

BASIC 6-16 

COBOL 3-20 

FORTRAN 5-8 

SPL 4-41,-53 
Optional parameters,KSAMUTIL 2-4 
Output only, 

BASIC 6-16,-18 

COBOL 3-4,3-21 

SPL 4-46,-54 



PACKED key type 2-15 
Parameter types,SPL 4-4 
Permanent file,close as 4-13 
Pointer dependence B-22 
Pointer,logical record, 

BASIC 6-7 

COBOL 3-9 
Pointers.SPL 4-5 

Position by chronological record,SPL 4-57 
Position by key sequence,SPL 4-26 



R 



R command (see RENAME) 
Random access code, COBOL 3-4,-21 
Random access,COBOL 3-22 
Random duplicate key insertion, 

BUILD 2-13 

FOPEN 4-49 
Random read, 

BASIC 6-26 

COBOL 3-29 

FORTRAN 5-10 

SPL 4-63 
Read by chronological record number,SPL 4-72 
Read chronologically, 

FORTRAN 5-13 

SPL 4-68 
Read randomly, 

BASIC 6-26 

COBOL 3-29 

SPL 4-63 
Read sequentially, 

COBOL 3-22 

COBOL example 3-48 

FORTRAN 5-10 

SPL 4-59 
Read user file label,SPL 4-76 
REAL key type 2-15 
Record numbering, 

BUILD 2-14 

FOPEN 4-48 
Record pointer, 

BASIC 6-7 

COBOL 3-9 

operation of B-23 

SPL 4-5 
Record size, 

BUILD 2-9 

FOPEN 4-41 
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Record type, 

BUILD 2-9 

FOPEN 4-45 
RECOVER option,KEYINFO 2-42 
Recover capability 1-7 
Recovery from system failure 2-27,-40;E-l 
Reload KSAM file E-ll 
RENAME command,KSAMUTIL 2-21 
Rename file.RENAME command 2-21 
Reorganize file capability 1-7 
RESTORE command,MPE 2-57 
Restore file 

from magnetic tape 2-57 

from serial disc 2-57 
Retrieve record capability 1-6 
Rewind file.SPL 4-17,-19 
Rewrite record, 

BASIC 6-29 

COBOL 3-32 

COBOL examples 3-34,-51 

SPL 4-92 
RPG interface 1-9 
RSAM conversion D-l 
RTOKSAM program D-l 



S command (see SAVE) 

SAVE command,KSAMUTIL 2-23 

Save file 

on magnetic tape 2-55 

on serial disc 2-55 

SAVE command 2-23 
Save permanent file,SPL 4-45 
Save temporary file, SPL 4-45 
Sectors per key block 2-38 
Security code,SPL 4-12 
Sequence check of key values 2-28 
Sequence checking, 

BASIC 6-20,-40 

COBOL 3-22,-42 

SPL 4-97 
Sequential access,COBOL 3-22 
Sequential access code.COBOL 3-4 
Sequential read, 

BASIC 6-22 

COBOL 3-26 

COBOL example 3-48 

FORTRAN 5-10 

SPL 4-59 
Sequential write, 

BASIC 6-39 

COBOL 3-42 

COBOL example 3-46 

SPL 4-97 
Serial disc.backup to 2-55 
Shared access, 

BASIC 6-7 

capability 1-8 

COBOL 3-10 

extra data segments B-21 

SPL 4-6 



Space forward/backward,SPL 4-88 
SPL 

interface 4-1 

summary of features 1-9 
Status checking, 

BASIC 6-4 

COBOL 3-6 
Status parameter, 

BASIC 6-4 

COBOL 3-6 
Status parameter values, 

BASIC A-6 

COBOL A-5 
STORE command,MPE 2-55 
STREAM command,use of 2-43 
Structure, KSAM files B-l 
SUBSET option,FCOPY 2-47,-52 
System failure, 

count 2-27 

recovery from 2-27,-40;E-l 
SYSTEM INTRINSIC statement, FORTRAN 5-2 

T 

Tape backup 2-55 
Temporary file 

close as 4-13 

creation.BUILD 2-9 

creation,FOPEN 4-45 

purging,FCLOSE 4-13 

purging.PURGE 2-20 

renaming,RENAME 2-21 
Terminal display,FCOPY 2-52 
Terminate FCOPY 2-45 
Terminate KSAMUTTL 2-4 

U 

Unlock file, 

BASIC 6-36 

COBOL 3-40 

SPL 4-91 
Update record 

BASIC 6-29 

capability 1-7 

COBOL 3-32 

COBOL examples 3-34,-51 

SPL 4-92 
Utilities, 

KSAM 2-1 

summary of 2-2 



V command (see VERIFY) 
Variable length records, 

BUILD 2-10 

FOPEN 4-45 
VERIFY command,KSAMUTIL 2-24 
Version request, 

BASIC 6-38 

SPL 4-103 
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w 



Write capability 1-6 
Write record, 

BASIC 6-39 

COBOL 3-42 

FORTRAN 5-9 

SPL 4-97 
Write sequentially ,COBOL example 3-46 
Write user label.SPL 4-101 
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